There is a new post which you can comment on to claim files.
We are pleased to announce the
JS docs initiative! It’s an ongoing effort to get all
JavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. files in WordPress well-documented and make this documentation easily accessible. JavaScript development within WordPress
core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is speeding up fast, and better documentation will help this work progress as smoothly as possible.
In the last few months, we’ve fixed the JavaScript documentation standards by discussing sticking points in the
#core-js weekly meeting. The structural documentation of all the Backbone classes has also been fixed (major props to
@herregroen for fixing this).
At the bottom is a list of every first-party JavaScript file in core. 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 using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.
How to contribute
- Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
- 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.
- Add the docs and javascript focuses.
- 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. Please also see the
JS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. 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
@since 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
@since Unknown.
If you use the git repository of WordPress you can also use git to determine the
@since version. Either use
git blame 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
@since annotation.
Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.
Note: All
@since 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 or
#core.
Files needing patches:
Checked files are completed, marked files are claimed
Current status:
Happy documenting!
#inline-docs
#javascript
