For those of you contributing to Inline Docs during Contributor Day Sofia 2013, we thank you. 🙂
The Inline Docs initiative is a part of the overall effort to build a new code reference that will live at developer.wordpress.org. Creating inline documentation for hooks will provide the information necessary to populate that portion of the code reference.
What You Need To Know
Please read the PHP Documentation Standard section on documenting Hooks (Actions and Filters) to familiarize yourself with how the actual doc block should be formatted, and how duplicate hooks should be documented.
- The Documenting Tips section covers recommended language when writing descriptions, as well how to determine the version for
@since, and guidelines for Code Refactoring. - The Formatting Guidelines section covers how to format the text in the descriptions.
Opening A Ticket > Getting Started > Trac Preferences explains how to log in to Trac with your WordPress.org username, and how to configure your email address in Trac preferences so that you receive Trac ticket notifications.
Working With Patches covers creating patches using the command line and TortoiseSVN (for Windows users). If you are using Git, please follow the creating patches guide at Contributing to WordPress Using Github by Scribu.
How to Contribute
We have reserved 15 files for the WC Sofia contributors to work on, and have tagged them (Reserved-WC Sofia) on the Add Inline Docs for Hooks post. The files are:
- wp-admin/network/edit.php
- wp-admin/network/settings.php
- wp-admin/network/site-new.php
- wp-admin/network/site-settings.php
- wp-admin/network/users.php
- wp-admin/user/admin.php
- wp-admin/includes/export.php
- wp-admin/includes/menu.php
- wp-admin/includes/template.php
- wp-admin/includes/theme.php
- wp-includes/functions.wp-scripts.php
- wp-includes/functions.wp-styles.php
- wp-admin/press-this.php
- wp-admin/update.php
- wp-admin/user-edit.php
The following are the steps you need to follow:
1. Leave a comment on the Make/Core post with the name of the file you are going to work on.
2. Update your local WordPress SVN or Git repo (use git pull) to the latest version of WordPress trunk (currently 3.8-alpha).
3. Create a new ticket on Trac for the file.
- Format the title as “Hooks Docs: path/to/file.php”.
- The Type should be “defect (bug)”.
- Assign the ticket to the “Inline Docs” component.
- Leave the Version blank.
- The Severity should be “normal”.
- Add your wordpress.org username or email address to the CC: field so you’ll receive activity notifications for your ticket.
4. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
5. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.
Patch Review Process
1. We will review your patch, and may make recommendations for changes that need to be made. We will change the ticket keyword to “needs-patch” if changes are needed.
2. Please read the review, ask for clarification if needed, then make the requested changes, and create a new patch.
3. Use the same filename for your revised patch, and upload it to the ticket. Remove the “needs-patch” keyword, and add the “has-patch” keyword.
- Note: Do not check the box next to Replace existing attachment of the same name – it is preferred to have copies of all attachments submitted to preserve the history of the ticket. Trac will automatically append an incremental number (xxxxx.2.diff) to the end of a patch filename to prevent an accidental overwrite of the existing file, in cases where the same patch is submitted multiple times due to needed changes.
We will review the updated patch, and may request further changes, if needed. Repeat steps 2 and 3 until we say your patch is good, and we tag it as “commit”.
Congratulations, and thank you for contributing to WordPress! 🙂