As I talked about in the core announcement, Drupal has experienced phenomenal growth over the past 14+ years. I wanted to take an opportunity to reflect on our current governance structure and try to evolve the Drupal leadership team and decision-making, enable better scaling, and document both the formal and informal processes we have currently in place.
What follows is a document builds on ideas that have been blogged about or presented at Drupal events by many people, and attempts to clearly document how things are currently done, and also proposes some incremental improvements. I've run this past the core committer team, as well as numerous others who've contributed to these conversations, and this policy draft is a result of that work.
I'd like to leave this open for feedback for two weeks, at which point I will incorporate feedback and finalize as a document in
https://www.drupal.org/project/governance →
.
---
Introduction
This document provides an overview of Drupal core's organizational structure, outlines what roles/responsibilities exist, and defines how decisions are made. The goal is to help the broader community understand the process, to ensure that both old and new maintainers understand their responsibilities, and to eliminate uncertainty about who has the ability to make decisions in various parts of the project.
This is a living document; if you see something out of date or missing, please file an issue in the
"Drupal core" issue queue →
with the "
Project governance →
" issue tag.
What is a core contributor? (#)
Anyone at all with a Drupal.org account can be a core contributor, simply by participating in the Drupal core issue queue. A core contributor is someone who:
- Posts bug reports and feature requests
- Uploads code changes ("patches") to the issue queue
- Reviews the behavior and code changes from a given patch
- Posts constructive, actionable feedback on how other core contributors can improve their work
- Performs "triage" of the issue queue, such as closing out duplicate issues, setting metadata properly
- Contributes their skills and experience such as architecture, design, accessibility, access to non-technical users, and development
- Various other collaborative activities
In short, core contributors are empowered to drive changes within Drupal's code base, and to work with other core contributors to help get changes they care about in, using a variety of both technical and non-technical skills.
Most proposed changes follow a standard peer review process, with sign-off from one or more maintainers (who are themselves a subset of core contributors).
What is a maintainer? (#)
(Thanks to Docker for the inspiration.)
There are different types of maintainers, with different responsibilities, but all maintainers have three things in common:
- They share responsibility for the project's success.
- They have made a long-term, recurring time investment to improve the project.
- They spend that time doing what needs to be done, not always what
is the most interesting or fun.
Maintainers are essential, but the results of their work are not always immediate or obvious. It's easy to appreciate a really cool and technically advanced feature. It's harder to appreciate the absence of bugs, the slow but steady improvement in stability, or the reliability of a release process. But those things distinguish a good project from a great one.
Potential maintainers generally demonstrate expertise, consistency, and passion contributing in their area before they become maintainers.
Maintainers with commit access need additional skills. They are reliable, decisive when needed, open to feedback, and able to give others feedback constructively. They also need significant prior experience participating broadly in core issues (usually at least a year).
It's generally desired to have at least two people in any given maintainership role, in order to prevent burnout and to help ensure there are ample people available for unblocking a given decision; however, this is not a hard requirement. Maintainers are expected to give clear, objective reasons and actionable feedback in the event they push back on a given change.
What are the different types of maintainers? (#)
The list below defines the different maintainer roles. (Detailed responsibilities for each role are outlined later.)
- The Benevolent Dictator for Life (BDFL): The founder and chief decision-maker for the project.
- Core Committers: The small subset of people who, along with the BDFL, can commit changes to Drupal core itself. Within the core committer team there are:
- Product Managers: Focus on user-facing features and Drupal's user experience.
- Framework Managers: Focus on cohesiveness of Drupal's architecture, APIs, and developer experience.
- Release Managers: Focus on processes to increase release stability, and on facilitating effective collaboration among contributors.
- Subsystem Maintainers: Maintainers of one particular part of Drupal core, such as the Entity system or Comment module.
- Topic Maintainer: Subject-matter experts in a topic that spans multiple subsystems—Accessibility, Documentation, Performance, Testing, and Usability. These correspond to the
core gates →
which all proposed changes must pass.
- Initiative Coordinator: Community members appointed by the BDFL to coordinate strategically important work. Initiatives are typically cross-functional in that they span different subsystems and different topics, and can affect both Drupal the product and Drupal the framework.
How are decisions made? (#)
Anyone with a Drupal.org account can create or update a Drupal core issue to propose a change. Issues should be processed according to the following flow:
- Drupal employs a
peer review process →
. All proposed changes require sign-off from someone other than the author(s).
- If a change doesn't significantly impact any given area of Drupal, it simply needs a peer's sign-off.
- If a patch significantly impacts a single subsystem, the maintainers of that subsystem must be given opportunity to sign off.
- If the change significantly impacts any area covered by a topic maintainer, that topic maintainer needs to approve or refuse it.
- If a subsystem/topic maintainer sign-off is not given in a timely manner, or if sign-off is not possible because the patch was authored by those who need to provide sign-off, it gets escalated to the core committers.
- If the change significantly impacts multiple subsystems, or represents a significant change in architecture or public APIs, the framework managers must approve or refuse it.
- If the change represents a significant new feature, UI change, or change to the "user experience" of the project, the product managers must approve or refuse it.
- If the change significantly affects the overall technical debt or release timeline of the project, the release managers must approve or refuse it.
- If the change affects the governance, philosophy, goals, principles, or nature of the project, it must be approved by the BDFL.
- Once a change has the required sign-offs, any core committer may commit it.
See the Frequently Asked Questions for explanations of what it means to sign off on a change and examples of what constitutes a "significant" change.
Also see the Responsibility Assignment Matrix version.
Who are the Drupal core maintainers, and what do they do? (#)
This section:
- Defines in detail each of the roles discussed above.
- Outlines their overall responsibilities and the tasks they're expected to do.
- Lists both the current and "provisional" membership of each role.
The BDFL (#)
BDFL stands for "Benevolent Dictator for Life." All decisions are made, by default, by the BDFL. However, since the BDFL making every decision would be highly un-scalable, in practice decisions are spread across multiple maintainers. The BDFL appoints and replaces those maintainers, and spends time thinking about how to make the team function well. The BDFL also holds final say in any disagreements, and can be escalated to when decisions cannot be reached through the normal process. Finally, the BDFL also preserves the philosophy, culture, and principles of the project.
Tasks
- Are there issues assigned to the BDFL which have been escalated by the other maintainers?
- If yes: either resolve them, or appoint someone to resolve them
- Are there "Project governance" issues that need review?
- If yes: appoint new maintainers, and/or replace maintainers.
- Is the project governance stuck in a deadlock, irreversibly fragmented, or off track?
- If yes: refactor the project governance.
Core Committers (#)
Core committers are the people in the project with commit access to Drupal core. Within the core committer team, the BDFL assigns people certain areas of focus (defined below) to help with decision-making. Nevertheless, core committers are a group of peers, and are expected to work closely together to achieve alignment, to consult each other freely when making difficult decisions, and to bring in the BDFL as needed.
In addition, note that the Documentation Topic Maintainer also has commit access for documentation patches only, across all major versions.
While core committers tend to stay focused on their particular versions, where needed they can step in to fill needs in other versions (for example, the Drupal 7 Release Manager rolling a security release for Drupal 6 at the same time). It's also possible that a non-technical Product Manager or Release Manager could be appointed at some point, who would only very rarely use their commit access. The distribution of committing work is something to be worked out among the core committer team.
Tasks
- Are there issues in the "Reviewed & tested by community" (RTBC) issue queue?
- If yes: Verify the issues have proper sign-offs and review the changes therein; commit the change or modify issue statuses/assignments as appropriate.
- Was a change escalated to your area of focus?
- If yes: Either make a decision or ask advice from one of the similarly focused committers.
- Does a change span multiple areas of core committer concern (product, framework, and, release management?)
- If yes: A relevant subset of committers meets as a group to discuss.
- Is there consensus among affected core committers on what to do?
- If yes: Post a summary to issue.
- If no: Escalate to the BDFL.
Core Committer: Product Manager (#)
Product managers are expected to talk extensively with different types of Drupal’s users, gather data about how Drupal is used in the “real world,” and present this information back to Drupal's various audiences.
The product managers are responsible for:
- Determining what user-visible features Drupal core ships with
- Drupal's out-of-the-box experience
- The overall integrity of Drupal’s user experience
- Representing the Drupal product's audiences (site builders, content authors, etc.) in core decisions
Significant changes to user-visible features, the user interface, and install profiles must be approved by the product managers.
Tasks
- Are there issues tagged "Needs product manager review"?
- If yes: provide feedback and make a decision.
Core Committer: Framework Manager (#)
The framework managers are responsible for the overall integrity of the technical architecture across all subsystems, the consistency of APIs, and the overall developer experience of Drupal.
Significant developer features, changes to public APIs, external libraries, and overall architecture must be approved by the framework managers.
Tasks
- Are there issues tagged "Needs framework manager review"?
- If yes: Provide feedback and make a decision.
Core Committers: Release Manager (#)
The release schedule is set by the BDFL in consultation with the other core committers, and the release managers make sure that we manage towards it. This includes rolling the releases, tracking the release schedule, facilitating communication between all participants, measuring progress, and defining the processes that help contributors collaborate effectively and efficiently. Release managers also make the final call on issue "metadata", such as status and priority, unless overruled by the BDFL.
Tasks
- Are there issues tagged "Needs release manager review"?
- If yes: Provide feedback and make a decision.
- Has the next release been scheduled?
- If no: Schedule it; if it's scheduled for today, tag it. Coordinate with the security team as needed.
- Are all release blockers and risks properly identified,triaged, and on a path to resolution?
- If no: Coordinate triage of critical issues or propose steps to accelerate them.
Topic Maintainers (#)
Some aspects of the project are system-wide and correspond to one of the core gates that all proposed changes must pass. Topic maintainers ensure that patches improve rather than cause regressions for these topics and help educate other contributors on how to do the same in their patches.
(*) While generally topic maintainers do not have core commit access, the Documentation Topic Maintainer is an exception and has commit access for documentation patches only, since they cannot functionally break the system. (Note that class annotations are not considered documentation.)
Tasks
- Are there any issues tagged "Needs $topic review"?
Subsystem Maintainers (#)
Subsystem maintainers oversee the development of parts of Drupal known as "subsystems". They can make a shorter-term commitment to maintaining a subsystem, or a longer-term commitment that spans several major Drupal versions.
The maintainers of each subsystem are responsible for:
- Communicating the vision for their subsystem.
- Delivering prompt feedback and decisions on issues affecting their subsystem when needed.
- Being available to other contributors with questions, bug reports, and feedback on their component, primarily on Drupal.org issues.
- Working with the security team to resolve security issues in the subsystem.
- Ensuring their subsystem respects the philosophy, design, and goals of the project.
- Periodically triaging their subsystem's issue queue to ensure that issues therein are relevant and current.
Anyone can be a provisional maintainer to a subsystem by simply contributing to it. Most subsystem maintainers start out contributing to their component by triaging issues, supplying patches, and reviewing others' patches.
Tasks
- Are there issues tagged "Needs subsystem maintainer review" in your component?
- Are there contributors in your queue who are providing consistently great code and reviews?
- If yes: File an issue with the "Project governance" tag recommending them as fellow subsystem maintainers.
- Are there fellow maintainers in your subsystem who are no longer active?
- If yes: Try and reach out to them first.If there is no response, file an issue against the "Project governance" tag recommending removal.
Subsystem maintainers also ensure that the issues in their queues are properly triaged, either through their own work or by organizing other contributors:
- Are there issues you've not yet responded to in your subsystem's issue component?
- If yes: Provide review and feedback.
- Are there duplicate issues in your subsystem, or issues that more rightly belong in another subsystem?
- If yes: Triage issue queue accordingly.
- Do some of the issues in your subsystem represent significant changes to user experience, architecture, release timelines, or one of the topics?
- If yes: Tag "Needs X review" accordingly.
Initiative Coordinator (#)
Initiatives are larger projects for the current development release that are intended to re-architect or otherwise improve large areas of the Drupal core code-base. The BDFL determines these initiatives. Each initiative has initiative coordinators who act as project and community managers with a strategic agenda, and help guide a team of people interested in helping the initiative to succeed. Initiative coordinators don't have direct decision making powers; rather, they work to build buy-in among those who do have decision-making powers (product managers, subsystem maintainers, topic coordinators, etc.).
Tasks
- Coordinate work on the initiative.
- Communicate the plans, progress, and needs of the initiative to the community and the other maintainers.
Frequently Asked Questions (#)
How is a "significant" change defined? (#)
Here are some examples:
- A typo fix in the documentation of the Batch API. This will not significantly impact the Batch API, nor will it significantly impact the topic of Documentation, so only a simple
peer review and sign-off →
is needed.
- A change in Entity API to the arguments of a method that's called from numerous core modules. The change will be a significant one to Entity API because it has impact on multiple modules. However, to each consuming module it will be a simple one-line fix and therefore insignificant to them. Only the Entity API subsystem maintainers' sign-off is needed.
- The introduction of a brand new configuration system API, which multiple subsystems are expected to use in a consistent way. In this case, current Configuration subsystem maintainer sign-off alone is not enough; because of the impact to multiple other subsystems, the framework managers must also approve the change (and will likely consult with multiple other subsystem maintainers who would be major consumers of that API in the process). Additionally, the Documentation topic maintainer will need to provide sign-off to ensure the documentation for this new system is clear and complete.
- Switching the order of fields on a configuration form. Unless done on a very frequently used page, chances are this would not qualify as a significant change, and simple peer-review sign-off would be sufficient.
- Introduction of a new UI pattern, such as a new tag selection widget. Depending on how widespread its use will be, this may require product manager sign-off, but will certainly require both Usability and Accessibility topic maintainer sign-offs to ensure product cohesiveness is retained.
- Redesign of the node creation form. Because this change will be to the most frequently-accessed screen for content editors, as well as one of the most frequent targets for module developers for enhancements, it has significant impact on multiple fronts. In addition to the Node module subsystem maintainer, product managers must approve this change (to ensure the quality of the default user experience of Drupal), as must Framework Managers (to ensure that contrib extensibility is retained), as must Usability and Accessibility topic maintainers (to ensure there are no regressions in those areas).
- Convert the code base from procedural to object-oriented code. While clearly something that will affect multiple subsystems and thus will fall to framework managers to sign off, this also will have impacts for the very nature of Drupal itself and its target audience, so BDFL sign-off is also required.
- A new release process is proposed to define what changes are/are not allowed during beta. This is squarely in the Release Managers' purview, but they should consult with the rest of the core committers (as well as other core maintainers if they so choose) when formulating a proposal. Any new release process will ultimately need to be signed off by the BDFL as well, since it will impact both the goals and governance of the project.
As a maintainer, how do I "sign off" on a change in an area I am responsible for? (#)
- Look for issues tagged "Needs $role review" for your role.
- Review each issue and provide feedback by leaving a comment.
- If the issue needs more work, set it to "Needs work" (NW).
- If you agree with the change, update the issue's summary to indicate that you have signed off on the change.
- If a committer set the issue back from "Reviewed and tested by the community" (RTBC) for your signoff and no other sign-offs are needed, set it back to RTBC.
- Remove the "Needs $role review" tag for your role.
- If you are a committer and no other sign-offs are needed, you can review and commit the change as appropriate.
Are there objective criteria for sign-offs or is it purely up to the maintainer? (#)
Drupal core has existing objective criteria for what changes can be accepted, including:
Maintainers both evaluate changes in terms of these criteria and provide specific guidance for their area based on their domain-specific expertise and overall plan. (Also see the overall
Drupal mission, values, and principles →
.)
What happens if sign-offs are missing? (#)
Any contributor can suggest that a change needs a particular sign-off and add the appropriate "Needs $role review" tag. (Refer to the Responsibility Assignment Matrix for guidelines.)
Core committers are ultimately responsible for assessing which sign-offs are needed or missing for a given change in the RTBC queue. If one or more sign-offs are missing, the committer will add the appropriate "Needs $role review" tag(s) and set the issue back to "Needs review" or "Needs work". (Also see How are patches committed?)
What timeframes are given for sign-offs before decisions are escalated? (#)
In general, when an issue is tagged as needing a particular signoff, it is the responsibility of the maintainers for that role to provide feedback within one week. If the review is not done within that timeframe, the issue should be escalated to the next step. For time-sensitive issues (such as critical regressions or issues that are blocking other work), this timeframe may be shortened or a committer may recommend a follow-up discussion instead.
Maintainers can and should take time off, whether for vacations or just because they feel the need to. However, when doing so, maintainers should let their co-maintainers and/or the core committers know about their impending absence and what they'd ideally like done with any issues that need their feedback in the meantime, such as delegating these decisions to another individual.
Also see I disagree with a patch that was committed, and it introduced problems with an area of core I am responsible for. What should I do? and How are patches committed?.
What are the issue tags used to alert maintainers that a signoff is needed? (#)
- Needs subsystem maintainer review (within the particular subsystem's issue queue)
- Needs usability review
- Needs accessibility review
- Needs performance review
- Needs documentation review
- Needs testing review
- Needs product manager review
- Needs framework manager review
- Needs release manager review
- Project governance
(There is no "Needs BDFL review" tag; issues should be tagged with "Project governance" if appropriate or otherwise simply be assigned to the BDFL by a maintainer.)
How is commit access allocated? (#)
The roles of BDFL, product manager, framework manager, and release manager have commit access and are collectively referred to as "core committers" (or "branch maintainers" for a specific major Drupal version). With the exception of Documentation, topic maintainers and subsystem maintainers do not have commit access.
How are patches committed? (#)
Core committers work together to provide timely feedback on all issues that are marked "Reviewed & tested by the community" (RTBC), either reviewing and committing patches or setting an issue back to "Needs work" (NW) or "Needs review" (NR) for additional work or (in the case of significant changes) for missing signoffs.
For the current development branch of Drupal, committers work together to provide feedback on issues in the RTBC queue as soon as their availability permits. For stable branches, committers may leave issues at RTBC for a longer period to ensure they are adequately reviewed by others.
Committers will sometimes assign an issue to a different committer who has more expertise for that issue or whose signoff is needed.
What is a "provisional" maintainer? (#)
A "provisional" maintainer is a maintainer who do not yet have full authority for their role, but is working alongside the primary maintainers with the aim to become a full-fledged maintainer in the future. "Provisional" product, framework, and release managers can perform the same sign-off duties as core committers, but do not yet have commit access.
Are maintainers required to have any particular skills/expertise? (#)
No. Maintainers can rely on others from the team to support them in areas where they have less expertise. For this reason, it is valuable to have a range of technical skills on the team, but there are no specific requirements like "at least one of the product managers must have a design/UX background" or "one of the architects must be a performance or front-end engineer".
Are there any provisions for various maintainers like "no more than X people from a certain company"? (#)
No. In general, maintainers consult others for any significant decision; see How are decisions made? above. Since decisions are made through a system of signoffs and consensus rather than by vote, this mitigates the effect of any one group having a larger majority. If there are concerns about a maintainer making biased decisions on behalf of a particular employer or audience, these can be escalated "up the chain" to the next level, up to the BDFL, or in a worst case scenario up to the
Community Working Group →
. (If there are simply objective concerns about a specific decision, a followup issue should be filed instead.)
What's the difference between a "Product manager" and a "Usability topic maintainer"? (#)
A product manager sets forth the "vision" for what Drupal will look like, and decides on its feature set. A Usability maintainer helps maintain that vision by enforcing usability guidelines and providing usability feedback in their patch reviews. It's expected that the product managers and usability maintainers will work closely with one another, by drawing on each others' expertise.
What's the proper way to add myself as a maintainer? What's the proper way to step down as a maintainer? (#)
In either case, file an issue in the
"Drupal core" issue queue →
with the "Project governance" issue tag. If stepping up, it's helpful to list a few issues you've helped with recently to demonstrate your track record. If stepping down, it's helpful to recommend another person to take your place (when possible).
I disagree with a patch that was committed, and it introduced problems with an area of core I am responsible for. What should I do? (#)
Cross-post a followup issue explaining your concern and reach out to the core committer. For urgent or critical regressions, reopen the original issue and request a revert.
Doesn't this structure add all kinds of overhead to the committing process? (#)
While it's possible that this process may introduce slightly more overhead, the intent is to simply formalize what is informally done anyway, and help make the decision-making process explicit so both contributors and maintainers know what to expect and who to talk to if they're stuck. Also, formally spreading sign-off responsibilities to the various parties will hopefully result in fewer RTBC patches being rejected by core committers and a faster and more efficient process for everyone overall.
Appendices
(#)
Appendix: Responsibility assignment matrix (#)
The following Responsibility Assignment Matrix illustrates the Drupal core decision-making process.
While the most common format for such matrices is RACI (Responsible, Accountable, Consulted, and Informed), this table uses a variation called PACSI (Perform, Accountable, Control, Suggest, Informed), which more closely matches the collaborative nature of our culture.
Key
Perform (P)
The role(s) that carry out the activity.
This is placed in the column of the role(s) that predominantly drive those changes, but this doesn't preclude other roles from also carrying out work.
Accountable (A)
The role(s) ultimately accountable for the correct and thorough completion of the task, and often the ones who delegate the work to the performer (P).
Control (C)
The role(s) that review the result of the activity (other than the Accountable, A). They have a right of veto and their advice is binding.
Suggest (S)
The role(s) consulted for advice based on their expertise. They provide non-binding advice.
These are role(s) whose input via two-way communication is actively sought, though this does not preclude others from making suggestions.
Informed (I)
The role(s) that must be informed of the result of the activity.
Matrix
Note that if a change includes multiple rows in this table, there will be multiple roles involved.
* The BDFL may proactively make or override these decisions if they deem it necessary.