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:

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:

  1. They share responsibility for the project's success.
  2. They have made a long-term, recurring time investment to improve the project.
  3. 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. (See How should maintainers in the same role share responsibilities? for more on maintainer teams.) 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.)

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:

  1. Drupal employs a peer review process. All proposed changes require sign-off from someone other than the author(s).
  2. If a change doesn't significantly impact any given area of Drupal, it simply needs a peer's sign-off.
  3. If a patch significantly impacts a single subsystem, the maintainers of that subsystem must be given opportunity to sign off.
  4. If the change significantly impacts any area covered by a topic maintainer, that topic maintainer needs to approve or refuse it.
  5. If the change is adding additional maintainers, other maintainers for that area must be given opportunity to sign off.
  6. 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.
  7. 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.
  8. 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.
  9. If the change significantly affects the overall technical debt or release timeline of the project, the release managers must approve or refuse it.
  10. If the change involves adding a new subsystem maintainer, a product, framework, or release manager must approve or refuse it (depending on the subsystem). (Any may commit a change to remove a subsystem maintainer at that maintainer's own request.)
  11. If the change is adding new full or provisional core committers, initiative coordinators, or topic maintainers, the BDFL must approve or refuse it. The same is true if there is any cause for concern with adding a maintainer, or if the change involves removing a maintainer except at their specific request.
  12. If the change affects the governance, philosophy, goals, principles, or nature of the project, it must be approved by the BDFL.
  13. 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:

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

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

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:

Significant changes to user-visible features, the user interface, and install profiles must be approved by the product managers.

Tasks

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

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

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

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:

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

Subsystem maintainers also ensure that the issues in their queues are properly triaged, either through their own work or by organizing other contributors:

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

Frequently Asked Questions (#)

How is a "significant" change defined? (#)

Here are some examples:

As a maintainer, how do I "sign off" on a change in an area I am responsible for? (#)

  1. Look for issues tagged "Needs $role review" for your role.
  2. Review each issue and provide feedback by leaving a comment.
  3. If the issue needs more work, set it to "Needs work" (NW).
  4. If you agree with the change, update the issue's summary to indicate that you have signed off on the change.
  5. 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.
  6. Remove the "Needs $role review" tag for your role.
  7. 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? (#)

(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 does 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.

How should maintainers in the same role share responsibilities? (#)

Multiple maintainers may share the same role; in fact, it often works best to have maintainer teams, as described in the definition of a maintainer. When there is more than one maintainer in a role, the maintainers collaborate to accomplish the tasks for the role. The maintainers may decide among themselves however they wish to share these responsibilities. They might share the tasks equally, or agree that a certain maintainer within the team will be responsible for a particular task, period of time, part of the subsystem, etc.

If the maintainers in a given role disagree on a decision in their area, the decision may be escalated to the next level.

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.

PACSI representation of decision-making process outlined above.

* The BDFL may proactively make or override these decisions if they deem it necessary.