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, 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/.
  • 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, #minor-releases, #release-process

Release Process Checklists

The release process is complex and beyond one person. Releasing is an intricate dance that we haven’t been sufficiently capturing. Knowledge siloed in heads needs to be committed to public, institutional memory. The upcoming 4.5 release is an opportunity to capture every step of the dance so that we can iterate process, automate away lingering drudgery, and improve our cognitive net for the stressful task of releasing to 25%. I like using checklists in this cognitive net. They relieve anxiety, make process transparent, and help teams flow during stress. We already have a couple release checklists. We can build on those while adopting a little checklist culture in a manner empathetic to developers and flow. Pitch:

Checklist cool tricks

Checklists…

  • distribute power.
  • push power of decision making to the periphery.
  • provide a cognitive net.
  • make the minimum necessary steps explicit.
  • make sure simple steps are not missed.
  • make sure people talk.
  • capture and shape real flow.
  • inspire flow in emergencies and sustain it through the quotidian.
  • capture flow between teams.
  • encourage a shared culture around flow.
  • accessibly capture institutional memory in the context of flow.

Attributes of a good checklist

What makes a good checklist? Checklist shouldn’t be about just checking boxes. Instead of being a chore and an admonishing finger, checklists should fit and assist real flow. The Checklist Manifesto offers these suggestions. Ideally, checklists…

  • are not lengthy.
  • have clear, concise objectives.
  • define a clear pause point at which the checklist is supposed to be used.
  • have fewer than ten items per pause point.
  • fit the flow of the work.
  • continually update as living documents.

See this checklist for checklists and this example checklist for more.

Stuff to checklist

The major release checklist attempts to use pause points and follow the suggestions above. The major and minor release checklists are pretty rough and incomplete and overlap with each other. These and the things to keep in mind list need love and unification with help from developers who are in the release flow and handling controls on the release train.

about.php is…quite the process. It needs the oxygenating powers of a checklist.

Checklist Feature plugin merges.

Checklist bundled theme releases so stuff like this makes it into institutional memory.

BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. and RC releases.

Plenty of other stuff. 🙂

Start by capturing. As we walk 4.5 release flows, capture.

Selected quotes from The Checklist Manifesto

Checklists supply a set of checks to ensure the stupid but critical stuff is not overlooked, and they supply another set of checks to ensure people talk and coordinate and accept responsibility while nonetheless being left the power to manage the nuances and unpredictabilities the best they know how.

Continue reading

#checklists, #pitch, #process, #release-process