Proposed Trac component reorganization

Warning, this long. tl;dr: I propose a reorganization of our TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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-adminadmin (and super 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 “Networknetwork (versus site, blog) Admin” ticketticket Created for both bug reports and feature development on the bug tracker. would go in the “Networks, Sites” component and receive the ‘multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site’ 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 headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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 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. 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 triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. 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 UIUI User interface (‘administration’ focus!) and the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.; 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 testunit test Code written to test a small piece of code or functionality within a larger application. Everything from themes to WordPress core have a series of unit tests. Also see regression. 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. HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. API
  17. I18Ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill.
  18. Import
  19. Mail
  20. Media
    • Upload
    • Embeds
    • Gallery
    • Image Editor (includes: API and UI)
  21. Networks, Sites
  22. Options, MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress., Transient APIs (added last week as “Options and Meta”)
  23. Permalinks (includes: link-template.php, SSLSSL Secure Sockets Layer. Provides a secure means of sending data over the internet. Used for authenticated and private actions.)
    • Canonical
    • Rewrite Rules
  24. Posts, Post Types
    • Post Formats
    • Post Thumbnails
    • RevisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision.
  25. PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party API (primarily, the hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. API)
    • Admin APIs (includes: Settings API, Screen API, Admin Menu, etc.)
  26. Query (includes: date, meta, tax)
  27. Script Loader
  28. Security
  29. TaxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format.
  30. Themes
    • Appearance (alt name: CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., 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)
  • TrashTrash Trash in WordPress is like the Recycle Bin on your PC or Trash in your Macintosh computer. Users with the proper permission level (administrators and editors) have the ability to delete a post, page, and/or comments. When you delete the item, it is moved to the trash folder where it will remain for 30 days. (has not been seriously used since 2.9; dissolved)
  • Blogblog (versus network, site) 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