Title: Continuing inline docs improvements adjacent to 4.8
Author: Drew Jaynes
Published: March 11, 2017
Last modified: March 12, 2017

---

 [  ](https://profiles.wordpress.org/drewapicture/) [Drew Jaynes](https://profiles.wordpress.org/drewapicture/)
12:54 am _on_ March 11, 2017     
Tags: [inline-docs ( 13 )](https://make.wordpress.org/core/tag/inline-docs/),
[minor releases ( 42 )](https://make.wordpress.org/core/tag/minor-releases/), [release-process ( 30 )](https://make.wordpress.org/core/tag/release-process/)

# Continuing inline docs improvements adjacent to 4.8

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 coreCore 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 releasemajor 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](https://profiles.wordpress.org/matt/), and the decision
has been made to go ahead and prioritize some inline docsinline 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 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](https://www.javascript.com/)
 * 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 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. will also need to be backported
   to the 4.7 (or current stable) branchbranch 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 releaseMinor
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](https://make.wordpress.org/core/tag/inline-docs/), [#minor-releases](https://make.wordpress.org/core/tag/minor-releases/),
[#release-process](https://make.wordpress.org/core/tag/release-process/)

### Share this:

 * [  Threads ](https://make.wordpress.org/core/2017/03/11/continuing-inline-docs-improvements-adjacent-to-4-8/?share=threads)
 * [  Mastodon ](https://make.wordpress.org/core/2017/03/11/continuing-inline-docs-improvements-adjacent-to-4-8/?share=mastodon)
 * [  Bluesky ](https://make.wordpress.org/core/2017/03/11/continuing-inline-docs-improvements-adjacent-to-4-8/?share=bluesky)
 * [  X ](https://make.wordpress.org/core/2017/03/11/continuing-inline-docs-improvements-adjacent-to-4-8/?share=x)
 * [  Facebook ](https://make.wordpress.org/core/2017/03/11/continuing-inline-docs-improvements-adjacent-to-4-8/?share=facebook)
 * [  LinkedIn ](https://make.wordpress.org/core/2017/03/11/continuing-inline-docs-improvements-adjacent-to-4-8/?share=linkedin)

 1.  ![](https://secure.gravatar.com/avatar/1a7df76f4f6519a5618c32428b277a5c7a89798394965b67e50528ca57c1b5a8?
     s=32&d=mm&r=g)
 2.   [Andrew Nacin](https://profiles.wordpress.org/nacin/)  6:16 am _on_ March 13,
     2017
 3.  Nice work [@drewapicture](https://profiles.wordpress.org/drewapicture/)!
 4.  There are some excellent intentions here (yay documentation!) but I think there
     are some technical drawbacks that need to be carefully considered. I’m honestly
     a bit concerned about this.
 5.  > 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.
 6.  This would be true if we have made major reliability/stability improvements to
     automatic updates in the last three years. I don’t believe this is the case.
 7.  Generally, update statistics have showed a clear correlation between failures 
     and I/O operations. This is clearly seen in the difference between minor releases
     of different sizes, and even more pronounced when comparing those to a major releasemajor
     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. like 4.7 (with hundreds of files changed).
 8.  Additionally, we run these updates using partial build packages. Every extra file
     adds a significant amount of KB to the package, which adds up pretty quickly. 
     This not only stretches the wordpress.orgWordPress.org The community site where
     WordPress code is created and shared by the users. This is where you can download
     the source code for WordPress core, plugins and themes as well as the central 
     location for community conversations and organization. [https://wordpress.org/](https://wordpress.org/)
     load balancers (when suddenly millions of sites are updating within an hour), 
     but also each individual site, which must download the ZIP, which takes time (
     partial builds made things, on many shared servers, go from minutes to seconds)
     and introduces lots of possibilities of download failures, and thus sites needing
     to retry later (and wait longer) to get patched.
 9.  Here’s some stats that points a finger squarely at I/O:
 10.  |  Version |  Files changed |  Package |  Failure rate |  Average time 
     (successful
     updates) |  
      |  **4.7** |  hundreds |  8.7 MB |  0.0719% |  34 sec |  
      |  **
     4.7.1** |  78 |  775 KB |  0.0055% |  16.8 sec |  
      |  **4.7.2** |  17 |  135 
     KB |  0.0019% |  12.9 sec |  
      |  **4.7.3** |  48 |  779 KB |  0.0028% |  13.3
     sec |
 11. I’m also somewhat concerned about cluttering branchbranch 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". history (I’d
     argue it’s pretty important for commits in security releases to be kept to a minimum),
     as well as introducing possible coding errors (which are rare but have occurred
     in the past when adding documentation).
 12. I saw a list of pros, but I’m curious what the end benefit is. Is it inline documentation?
     Is it developer.wordpress.org? I would be interested in a proposal that pushes
     documentation updates to developer.wordpress.org, without actually touching files.(
     I’m also interested in partial builds that excludes files when only documentation
     lines are changed, though that sounds insane and please don’t actually pursue 
     this…)
 13. ![](https://secure.gravatar.com/avatar/62ed6669556644a294591975f01137cd76ea6d1dcd8bf8b3328c1e2bf6e2a80d?
     s=32&d=mm&r=g)
 14.  [Dion Hulse](https://profiles.wordpress.org/dd32/)  11:27 pm _on_ March 22, 2017
 15. I hadn’t seen this post until now – but have to echo Nacin’s remarks above, backporting
     a lot more is going to reduce our ability to keep sites secure – even if it’s 
     only a tiny percent of sites affected, it’s still a less secure outcome for everyone.
 16. That being said, I support backporting some documentation changes – specifically
     _address some glaring docs errors that we’ve been fixing manually in the Code 
     Reference_ which I believe we should have already been doing.

Comments are closed.

# Post navigation

[← Dev Chat Agenda for March 8th (4.7.4 week 1)](https://make.wordpress.org/core/2017/03/08/dev-chat-agenda-for-march-8th-4-7-4-week-1/)

[Continued Discussion on Browser Support →](https://make.wordpress.org/core/2017/03/13/continued-discussion-on-browser-support/)