This initiative follows the inline docs initiative with a specific focus on JavaScriptJavaScript 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/.. The goal is to get all JavaScript files in WordPress well documented and make this documentation easily accessible. JavaScript development within WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is speeding up fast and becoming more and more prominent given the current core editor and REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. focuses. To help these developments progress as smoothly as possible, we need to make sure the existing code is documented well.
If you’re not familiar with what inline documentation is, read our page on inline documentation standards.
Which JS files should be documented?
There are three pages tracking JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. files for documentation:
- Unclaimed JS docs files: Nobody is working on documenting these files yet. You can claim a file by commenting on the post.
- In progress JS docs file tickets: These files have patches with documentation or someone is working on creating a documentation 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..
- Closed JS docs file tickets: These files have been documented already.
How to get involved
Inline documentation is considered to be “technical” documentation, so some familiarity with the WordPress codebase will be necessary – you have to understand the code to write about it.
1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
2. Set up a local copy of the developer version of the WordPress codebase using Varying Vagrant Vagrants (VVV). WordPress is versioning using SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase., but you can also use 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. https://git-scm.com/. (the VVV link for how to do that).
3. Read Opening a Ticket to learn how to create a TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker..
4. Creating patches:
- Claim a file to start documenting.
- Always update your local copy 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. before editing the file and creating patches. Use
svn up
orgit pull
, as appropriate. - Generate the patch from the root directory of your WordPress SVN or Git checkout.
- It is best to name your patch file with the Trac ticket number you created, such as 12345.patch or 12345.diff. Either file extension is acceptable.
5. How to submit a patch:
- Create a new ticket on Core Trac for the file:
- Suggested Title formats could be “JSDoc correction for path/to/file.js” or “Improve documentation for path/to/file.js”.
- 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 ticket to the Component the file is associated with.
- Leave the Version blank.
- Add the docs and the JavaScript Focus by clicking on it.
- Here’s a shortcut link to create a new ticket in the
Media
component with thedocs
andjavascript
focuses and the titleJSDocs correction for
, all that is left to add is the filename in the title: New JSDocs Ticket
- Upload your patch to the Trac ticket you created, and add the keyword has-patch.
- Make sure to leave a comment describing your newly-uploaded patch. Simply uploading patches doesn’t trigger a notification for anyone watching the ticket.
- Note: Documentation changes should not mix with code changes (even whitespacing) unless the ticket specifically calls for both.
6. You can also contribute to inline docs-related Trac tickets that need iteration.
- If a ticket is marked needs-patch or needs-refresh, it’s possible the existing patch(es) might just need a touch-up or be refreshed against the latest trunk. Every little bit helps!
Points of contact
For any questions, pop by the #docs channel in Slack. For JavaScript specific questions, you can also join the #core-js channel.