Contributing to PHP: How to Contribute to PHP's Manual

This two-part series explores how to contribute to the PHP project, focusing on documentation in part one. We'll cover account requests and post-approval steps.

Key Points:

• Contributing to PHP's documentation enhances the language and boosts your PHP expertise. It can also lead to a php.net account, influencing the language's direction.
• The documentation uses DocBook XML; familiarity is helpful but not mandatory.
• Beginners can use the online editor for simple patches. Reviewing style guidelines beforehand is advisable.
• Frequent contributors or those needing extensive edits should set up the docs locally and request a php.net account. This involves creating a directory, cloning the docs, and configuring SVN keywords.
• Contributions include bug fixes, translations, expanding existing content, documenting undocumented features, and general improvements.

Why Contribute?

PHP, being open-source, thrives on community involvement. Increased participation benefits everyone. Whether it's improving documentation, fixing bugs, or adding features, every contribution counts. Active participation deepens your PHP knowledge and allows you to request a php.net account, shaping the language's future.

Understanding PHP's Documentation

The documentation is in DocBook XML. Prior knowledge isn't strictly necessary; the XML syntax is easily learned.

The directory structure is:

doc-base contains tools for converting XML documentation. en holds the English documentation (other languages use their two-letter codes). reference contains extension-specific directories (functions for procedural extensions, class-named folders for object-oriented ones). Each extension folder includes book.xml (landing page) and versions.xml (versioning info).

The documentation is currently SVN-based (though migrating to Git). Local setup requires SVN familiarity.

First-Time Contributors

Begin by using the online documentation editor. This allows OAuth login and submission of simple patches. Consistent account use simplifies tracking contributions for future php.net account applications.

Familiarize yourself with style guidelines before submitting patches.

Example: Resolving Bug #71716

This bug reports an incorrectly namespaced MongoDB Client class in a sample. After verification, use the online editor to correct the namespace.

Video Embed: https://www.php.cn/link/14aa36297925d3c82891d74fa28d7df1 (Replace with actual embed code if needed)

Local Setup

The online editor is limited; for more substantial contributions, set up the docs locally and request a php.net account.

1. Create a phpdocs directory.
2. Clone the docs using SVN: svn checkout https://svn.php.net/repository/phpdoc/modules/doc-en
3. Clone PhD (rendering tool): git clone http://git.php.net/repository/phd.git
4. Clone the php.net website: git clone http://git.php.net/repository/web/php.git web-php; remove web-php/manual/en and create a symbolic link to the rendered docs.
5. Configure SVN Keywords in ~/.subversion/config: *.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL
6. (Optional) Create a ref file with commands for validation, building, and viewing docs locally.

Docs Workflow (Local)

After setup, update repositories (svn up and git pull). Edit the relevant XML file, validate using php ~/phpdocs/doc-en/doc-base/configure.php, build with PhD, and start the local server. Commit changes using SVN (svn ci -m "Resolve doc bug #..."), referencing the bug number. Close the bug report from the "Developer" tab after changes propagate.

Requesting a php.net Account

After local setup, request a php.net account with docs karma. While no strict prerequisites exist, demonstrating active contribution is key. Submit the account request form and email phpdoc@lists.php.net explaining your intentions, wiki username, and past contributions.

Documentation Tasks

Beyond bug fixes:

• Translations
• Expanding partially documented material
• Documenting undocumented features
• General improvements

General Tips

• Follow style guidelines.
• Check related aspects when fixing bugs.
• Write concisely.
• Separate example code from output.
• Ensure correct page order.
• Remove PHP 4 references.
• Properly version new files.
• Consult the docs FAQ or php-docs mailing list for assistance.

Conclusion

This part covered two workflows: online editor and local setup. Part two will cover contributing to PHP's core.

FAQs (moved to the end for better flow)

• Contributing process: Create an account, edit/create content, translate, follow guidelines.
• Importance of contribution: Improves documentation quality, keeps it up-to-date, fosters community.
• Ensuring acceptance: Follow guidelines, ensure accuracy and clarity, get feedback.
• Non-native English speakers: Contributions are welcome; translation is a valuable contribution.
• Common mistakes: Not following guidelines, inaccurate/unclear info, lack of proofreading, unnecessary changes.
• Getting help: Use online forums, discussion groups, documentation guidelines.
• Anonymous contribution: Possible, but an account is encouraged.
• Contribution frequency: Varies based on availability and interest.
• Compensation: Generally volunteer work.
• Reporting mistakes: Correct them if a contributor, otherwise report to the community.

Remember to replace the placeholder image URLs with the actual image URLs. I've preserved the image formatting and kept the images in their original positions as requested.

The above is the detailed content of Contributing to PHP: How to Contribute to PHP's Manual. For more information, please follow other related articles on the PHP Chinese website!