Providing more clarity in the Gutenberg GitHub Repo

For a while now, the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repo has had a few high level labels (Overview, Tracking, Iteration) that have gotten a bit convoluted over time. Sometimes the issue is no longer relevant, is incorrectly labeled, has been updated so many times that the comments don’t follow what’s there, or double labeled. This has led to reported concerns and confusion around what work is truly active, what areas are being explored, and more. To begin to clean this up, a few things were done over the last week or so to make these labels more reliable, more consistent, and easier to follow:

  • Updating the descriptions of these labels to be concise, more descriptive, and show how they are tied to each other.
  • Changing Epic to Iteration for clarity as Epic holds different connotations for folks and is harder to grasp.
  • Triaging older issues and closing out when necessary aka the work is no longer relevant or has been completed.
  • Ensuring the labels that remain are accurate, either by not labeling the work as one of the above labels or adding/removing labels.
  • Pinging the folks who opened different issue when needed to ask for updates to ensure what’s there aligns.
  • Opening any needed overview issues related to phase 3 (this is in progress by @priethor). 

How can I use or interact with these labels? 

For context, here’s a sense of how each label should work and how you might want to use them or follow them:

  • Overview issues contain more context/strategy and narrative, often including multiple tracking issues to accomplish an area of work and existing across numerous releases. Here’s an example from phase 2.
  • Tracking issues are more tactical, broken down into individual tasks and areas of work, and exist across a few releases. It should ideally be part of a breakdown from an Overview issue. Here’s an example for layout support.
  • Iteration issues are to define iterations of a project in smaller deliverable packages, including when possible the minimum requirements to ship the iteration as a whole in a WordPress release. Expect these issues to be regularly updated and curated. They reflect more active work and often is pulled out of a list of items in a tracking issue unless the scope is small and it can pull work directly from an Overview. Here’s an example with overrides in synced patterns for 6.6.

This means if you don’t have a ton of time to pay attention to the releases or overarching work, you can use these labels to narrow your focus and stay up to date at the level you’d like. 

Label description updates

This is just a quick rundown of what’s changed, description wise, to tighten up the approach. 

Before:

  • Epic: A large body of work shaping an iteration that can be broken down into a number of smaller issues.
  • Tracking: For issues used to track large changes across the codebase
  • Overview: Offers a comprehensive breakdown of a specific area of work to act as a guidepost

After:

  • Iteration: Scoped iteration of an effort from a tracking issue or overview issue ideally for 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..
  • Tracking: Tactical breakdown of efforts across the codebase and/or tied to Overview issues.
  • Overview: Comprehensive, high level view of an area of focus often with multiple tracking issues.

Let’s keep iterating

This system isn’t perfect but, just like with WordPress itself, it’s an iteration and you can expect more to come. This will be focused on for the WordPress 6.6 cycle on the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Editor side and likely iterated upon once more after going through a full cycle with a more tightened workflow. If done well, very little extra work should be created for contributors and those who want to contribute or follow along the efforts can do so with greater ease. Ultimately, communication around what’s gone into a release happens already and this just seeks to formalize where it happens with clearly high level labels and norms within them. 

Thank you to @richtabor and @priethor for reviewing this post. 

#core-editor, #gutenberg