Add Inline-Docs for Hooks

The time to document ALL THE HOOKSHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. used throughout coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is nigh.

We’ve hashed out the process in a couple of different meetings in #wordpress-dev, and we’ve added a new page to the Core Contributor Handbook that covers the broader PHPDoc standards, as well as the specific hook documentation standards (the praise for the bulk of that work should go to @kpdesign and @drewapicture, by the way).

At the bottom is a list of every file in core that has a call to either do_action() or apply_filters(). Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re attempting to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute:

  1. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  2. Update your local WordPress SVN or GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. repo (use git pull) to the latest version of WordPress trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. (currently 3.9-alpha).
  3. Create a new ticket on Trac for the file.

    New Hook Docs Ticket Example

    • Format the title as “Hooks Docs: path/to/file.php”.
    • The Type should be “defect (bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.)”.
    • Assign the ticketticket Created for both bug reports and feature development on the bug tracker. to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs focus.
  4. Edit the file, and make a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing.. Please make sure you create the patch from the root directory of your WordPress SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. or Git checkout.
  5. Upload your patch to the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket you created, and add the keyword “has-patch”.

*Note: We strongly encourage you to work on very few files at a time. In many cases, one at a time is probably best. In some cases it may make sense to tackle several at once. The important thing is that you realize your edits should be made and patched swiftly so that they aren’t invalidated by (or don’t invalidate) another patch. It’s also important to note that we’re working with a small time-table, and need to be able to claim, edit, patch quickly — which is hard to do if someone were to lay claim to 20 files at a time, and then sit on them for a few days.

Determining the since version for hooks

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

Note: All @since tags should follow the three digit x.x.x format, unless it was ported from MU. Anything ported over from WPMU should use @since MU. Existing @since MU tags should not be changed.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly Inline Docsinline docs (phpdoc, docblock, xref) meeting on Wednesdays at 19:00 UTC in #wordpress-sfd.

Files needing patches:

Checked files are completed, marked files are claimed

Current status:

#3-7, #inline-docs