Proposed Trac component reorganization

Warning, this long. tl;dr: I propose a reorganization of our Trac components. 34 top-level components with two dozen subcomponents. New tree at the bottom. First, an overview of some of our problems.

Administration and Template components

These two components have become a dumping ground for tickets. They are ill-defined components with significant overlap — indeed, nearly all areas of core have both administration and templating angles.

After our initial run of focuses last week, a number of us have noted how they appear to be an effective tool to solve this problem. We’ve been planning to do a “component tree” — as in, having subcomponents. But it doesn’t make sense to have a dozen or more components simply with the name “Administration” and “Template” and nested under Users, Posts, Comments, Widgets, Menus, Plugins, etc. They aren’t functional, specific areas of core that a component ought to be. “Users” describes wp-admin/users.php, wp-includes/user.php, and wp-includes/author-template.php far better than “Administration” or “Template.” Additionally, if we want to teams to grow around these areas, it makes most sense to group them around functional components.

So, I’d like to propose we make ‘administration’ and ‘template’ focuses instead.

  • A “Network Admin” ticket would go in the “Networks, Sites” component and receive the ‘multisite’ and ‘administration’ focuses. (Trac would automatically assign a ticket in this component the ‘multisite’ focus already.)

  • A ticket for the_content() would go in the “Posts” component and receive the ‘template’ focus.

  • A ticket for the Menus screen would go in the “Menus” component and receive the ‘administration’ focus. Or, if it has to do with template tags for Menus, it can be assigned the ‘template’ focus.

  • get_template_part() tickets belong in the Themes component with the ‘template’ focus. wp_login_form() is the “Login and Registration” component, ‘template’ focus. wp_get_archives() tickets would probably find themselves in the General ticket, ‘template’ focus.

  • The Appearance component includes custom header and custom background tickets, which mean both ‘administration’ and ‘template’ focuses would be in use here to differentiate.

  • The General component can be used combined with any focus to describe a ticket that is not specific to a component of core. A wide-ranging JavaScript standards ticket would be “General” and ‘javascript,’ or a cleanup across the admin area might be “General” and ‘administration.’ General should stop being a dumping ground in and of itself. (If necessary, we can introduce a new “Uncategorized” component to serve the role as the default.)

An added benefit of these focuses is it means developers very interested specifically in administration or our templating functions will have an all-encompassing focus from which to work. This enables contributors to specialize as they see fit (and, well, to focus). For more on focuses, see last week’s post.

(A note: This is all reversible. If we later determine this is a bad idea and we need to migrate away from focuses, it would not be difficult to do so.)

The Query component

There is another component with a bit of overlap: Query. Currently, there are query objects in WordPress for posts, comments, users, and helpers for dates, taxonomies, and metadata. In the future, we may also see one for terms and a WP_Order_Query helper. I do not think this is a focus, though. Rather, these describe very specific, functional areas of core — there are just a lot of them. Date query tickets belong in the top-level “Query” component. Tickets for WP_User_Query should go in a “Query” subcomponent under “Users.” Those interested in the “Query” component would likely be interested in the various “Query” subcomponents, of course.

Proposal overview

This is my wall right now.

This is my wall right now.

After studying our components for an extensive period, it’s clear to me “focuses” were what we needed to break the logjam. And so I’d finally like to propose taking our 60-something components and shuffle them into a tree.

It contains just 34 top-level items, which are clearly organized around functional areas of core. Ambiguities as to where a ticket goes that trip even me up should largely be resolved. It looks mostly the same, with not a whole lot of changes beyond adding some hierarchy. (I’ve been mocking up component trees for two years now. Earlier plans were much more radical, but focuses make that less of an issue.)

Nine of these 34 items have 24 subcomponents (1-4 each). So why subcomponents? Subcomponents mean we can be both more granular and less ambiguous. You no longer need to pick between two similar components — chances are, one is a parent component of another.

Subcomponents can also be added as needed, especially for new features or tasks, or if a component maintainer sees an optimization that would help them manage their component better. If there’s no longer a demand for a subcomponent, it can simply be removed without hassle, and new tickets can be targeted for the top-level component instead. The current list of components has bloated, and we have been slow in the past to add new ones. That should no longer be an issue.

Having just three dozen top-level components also means it will be a lot easier for teams to form around them. (Anyone can be a component maintainer, helping to triage new tickets, look after existing ones, spearhead or mentor tasks, pitch new ideas, curate roadmaps, provide feedback to others, etc.)

A number of existing components are removed in this tree, either dissolved, absorbed by another component, or turned into a focus. For the moment, only two are added — a new “Image Editor” subcomponent for Media, focusing on both the UI (‘administration’ focus!) and the API; and an “Admin APIs” subcomponent for Plugins, to catch tickets for the settings API, screen API, and admin menu API. (Also, the “Query” subcomponents discussed above.)

I’ve also been experimenting with a new autocomplete-style component selector. The words you type should be matched not only with components and subcomponents, but keywords for those components (which could include class or file names). Searching for “settings” would find the Admin APIs component with ease, “background” would find the Appearance component, and “date query” would find the Query component. If you’d like to help build this, please let me know. I’d love to have something going this week.

Some name changes occurred, as well — moving away from slashes in component names as these will be used to delineate subcomponents, and adding “API” in a few components. “Cache API” makes it clear it isn’t for caching issues in a comments function. Those belong in “Comments” (performance focus).

Proposed component tree

Changes (adds, renames) are in bold.

  1. Bootstrap, Load (added last week)
  2. Build, Test Tools (added last week as Build Tools; now includes unit test framework)
  3. Bundled Theme
  4. Cache API
    • Pings and Trackbacks
    • Query
  6. Editor
    • TinyMCE
    • Press This
    • Autosave
    • Quick and Bulk Edit
  7. Cron API
  8. Database
  9. Date and Time
  10. Export
  11. External Libraries
  12. Feeds
  13. Filesystem API
  14. Formatting
    • Shortcodes
    • Charset
  15. Help, About
  16. HTTP API
  17. I18N
  18. Import
  19. Mail
  20. Media
    • Upload
    • Embeds
    • Gallery
    • Image Editor (includes: API and UI)
  21. Networks, Sites
  22. Options, Meta, Transient APIs (added last week as “Options and Meta”)
  23. Permalinks (includes: link-template.php, SSL)
    • Canonical
    • Rewrite Rules
  24. Posts, Post Types
    • Post Formats
    • Post Thumbnails
    • Revisions
  25. Plugin API (primarily, the hooks API)
    • Admin APIs (includes: Settings API, Screen API, Admin Menu, etc.)
  26. Query (includes: date, meta, tax)
  27. Script Loader
  28. Security
  29. Taxonomy
  30. Themes
    • Appearance (alt name: Customizer, Header, Background)
    • Widgets
    • Nav Menus
  31. Toolbar
  32. Upgrade, Install
  33. Users
    • Role and Capability
    • Login and Registration (added last week)
    • Query
  34. XML-RPC

There are a few other changes to consider in the future:

  • We could probably benefit from a component for Dashicons.
  • External Libraries should probably be a focus.
  • The dashboard screen (widgets and such) could benefit from a component, but it’s tough to name.
  • Bundled Theme could benefit from a subcomponent for new themes in development (or for each theme). It’s possible these could be moved under Themes, too.
  • We’ll want a Bookmarks component to collect our Links-related tickets in one location to help us manage our technical debt.

Here are the components removed:

  • Network Admin (admin focus, Networks/Sites component)
  • Trash (has not been seriously used since 2.9; dissolved)
  • Blog by Email (merged with Mail)
  • IIS (dissolved, most of these were better elsewhere)
  • Text Changes (this will become a focus, for wordsmiths — needs a name)
  • Unit Tests (merged with Build Tools to create “Build, Test Tools”)

I’ll finally note that this was not just me. I’d like to thank @ocean90, @helen, @sergeybiryukov, @scribu, @markjaquith, @duck_, @koop, and @jeremyfelt (and many others) for weighing in on various proposals going back more than a year. Thanks!

Phew. What do we think? These would be our next steps:

  • Add the new ‘administration’ and ‘template’ focuses, and rename any components, add any new components.
  • Triage the hell out of the Administration and Template components. Plugins will also need a lot of love.
  • Add the concept of subcomponents, rearranging the existing components and launching new UI for it.
  • Launch component-based notifications (you’ll be able to subscribe to any/all of these components, as well as milestones and focuses).

#components, #trac