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’s inline documentation relied almost entirely on a regular, major release 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 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
- Prioritize docs improvements for existing functionality in the three focus areas ahead of the 4.8 release, 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 will also need to be backported to the 4.7 (or current stable) 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 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
