Inline Docs Tasks – WC Sofia Contributor Day 2013

For those of you contributing to Inline Docs during Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of There are many teams that people can participate in, each with a different focus. 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 The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. Creating inline documentation for 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. will provide the information necessary to populate that portion of the code reference.

What You Need To Know

Please read the PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. Documentation Standard section on documenting Hooks (Actions and Filters) to familiarize yourself with how the actual doc blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. 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 username, and how to configure your email address in Trac preferences so that you receive TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub. ticket notifications.

Working With Patches covers creating patches using the command line and TortoiseSVN (for Windows users). If you are using 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., 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 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 SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the released code are all centrally managed through 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! 🙂

#contributor-day, #inline-docs, #wcsofia