There is a new post which you can comment on to claim files.
We are pleased to announce the JS docs initiative
is speeding up fast, and better documentation will help this work progress as smoothly as possible.
weekly meeting. The structural documentation of all the Backbone classes has also been fixed (major props to @herregroen
for fixing this).
are already claimed, and being worked on.
Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.
How to contribute
- Check the list first to make sure the file you want to work on hasn’t already been claimed.
- Update your local WordPress SVN (use
svn up) or Git repo (use
git pull) to the latest version of WordPress trunk 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..
- Create a new ticket on Trac for the file.
- Format the title as “JSDoc: path/to/file.js”.
- The Type should be “defect (bug 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 ticket Created for both bug reports and feature development on the bug tracker. to the component the file is associated with.
- Leave the Version blank.
- Edit the file, and make a patch 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 SVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. or Git 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. https://git-scm.com/. checkout.
- Upload your patch to the Trac 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”.
We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments.
docs handbook page for a step by step guide on how to get started
Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.
Determining the since version
We use JSDoc’s
tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.
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
If you use the git repository of WordPress you can also use git to determine the
version. Either use
or the GitHub blame function
. Once you have the commit hash which introduced a piece of code you can find out the version by using
git tag --contains [commit-hash]
. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the
tags should follow the three digit x.x.x format.
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 devchat. That’s either #core-js
Files needing patches:
Checked files are completed, marked files are claimed