As we’re now into the full throes of the 4.8 cycle, the uncertainty that comes with not releasing “until it’s ready” inevitably creates a lull in areas other than the three focuses. Areas like maintaining our inline documentation, which populates the official Code Reference.
In the past, the freshness of core Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s inline documentation relied almost entirely on a regular, major release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. schedule. And due to a preference for keeping the number of changed files low, inclusion of docs fixes in minor releases has previously been a rare occurrence.
Until now.
I’ve spoken with @matt, and the decision has been made to go ahead and prioritize some inline docs (phpdoc, docblock, xref) fixes for inclusion in minor releases going forward.
As with any decision, there are certainly pros and cons. Here are some of them:
Pros:
- Ability to continue our ongoing inline docs maintenance adjacent to the 4.8 major release
- Ability to address some glaring docs errors that we’ve been fixing manually in the Code Reference
- Continue forward progress in documenting core 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/.
- Prioritize docs improvements for existing functionality in the three focus areas ahead of the 4.8 release A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software., freeing up resources for documenting new functionality
Cons:
- Number of changes and changed files in minor releases will increase (within reason)
- All changes pushed to 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. will also need to be backported to the 4.7 (or current stable) branch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch".
It’s worth noting that the reason the number of changed files has traditionally been kept low is to reduce the number of automatic update failures. The hope is that since we’ve been pushing automatic updates for 10 major versions now, reliability is less of a factor now than it has been previously.
It’s also worth noting that we shouldn’t expect a downtick in activity for core team resources focused on the three areas following this decision. As always, inline docs contributors will be focused on major release priorities before minor release A set of releases or versions having the same minor version number may be collectively referred to as .x , for example version 5.2.x to refer to versions 5.2, 5.2.1, 5.2.3, and all other versions in the 5.2 (five dot two) branch of that software. Minor Releases often make improvements to existing features and functionality. ones.
This decision simply maintains the inline docs team’s ability to ensure the usefulness of core’s source documentation for the thousands of users and developers who rely on it every day.
#inline-docs, #minor-releases, #release-process
