Co-maintaining projects

Last updated on
21 December 2022

This page outlines the best practices to follow when you have more than one maintainer of a project, to avoid conflicts and work together as a group to improve the project. See also Dries' blog post on Responsible maintainers.

Applying to be a co-maintainer

Everyone can submit patches to every project at any time. Co-maintainers are individuals who usually have the permission to make commits and thus change a project code. If a project is not being maintained, you may be able to become the maintainer.

  • Commit access is not granted blindly. Applicants should have already read each issue and participated in many issues in a project's queue, helped with support requests, provided patches, and be involved in architectural and technical discussions. Ideally, applicants are also available in IRC or other instant messaging tools used by the project maintainers.
  • Project maintainers should have committed 3-4 of your patches without any objections or remarks. Too simple patches do not count.

Code guidelines

  • All code fully adheres to Drupal's coding standards, commenting and documentation standards, and all other development standards.
  • All text visible to the user is translatable.
  • All code complies with Coder module review rules.
  • All changes, especially new features and improvements, are done for the newest official branch first and possibly back-ported afterwards.
  • If applicable, patches should be supplied for every branch of a project. However, focus on the latest major version first.
  • Discuss each change in a separate issue.
  • Create issues for almost all changes, even if you could commit them directly. This not only allows others to review them, but is also the only way to adhere to Drupal's guidelines for commit messages.
  • When porting a module to a new version of Drupal core, keep changes minimal and focused. Meaning: no code clean-ups, no new features.
    • Defer larger improvements, rewrites, and optimizations to separate follow-up issues, in case the new Drupal core allows for any. They can be done later, and depending on API changes, possibly in a new major version of the project.
    • The goal is to make fast progress, allowing users to adopt the new version of Drupal core and your project.
    • Read and understand the meaning of major versions below.
    • Create project's change records for ability to help other developers to understand how to update dependent code to next major release.

Committing guidelines

  • No non-trivial changes are committed without a corresponding issue on drupal.org.
  • Patches need to be reviewed by others and must be in RTBC state before committing them.
    • Ideally, another project maintainer reviewed them and had no objections.
    • However, if patches are unnecessarily held off because of missing reviews, then they should be committed, so development can go on. Project maintainers are often involved in many other projects, and they have a life, too.
  • (Optional) Before committing a major change, add a change log entry to CHANGELOG.txt that summarizes the change. Wrap the text at 80 characters. Some projects are listing all changes in CHANGELOG.txt; you should follow the existing or agreed-on practice.
  • Follow the best practices for commit messages.
  • If you've been granted limited commit access to maintain a certain part of the project only, then you will not commit any changes that affect other parts of the project.
  • Again, no commit without an issue.

Release guidelines

  • Tag all issues that prevent a new release with Release blocker.
    • Do not use version-specific release blocker tags. The combination of the tag and the assigned version of an issue is sufficient.
  • Discuss and coordinate the ongoing development and tasks for a certain release by creating a release coordination issue.
    • Use [project name] [new version] as issue title.
    • Use the issue summary to outline and link to all issues, ideally categorized. This allows you to edit and update the list afterwards.
    • Examples: Administration menu 6.x-1.2
  • Before creating a new release:
    • (Optional, if using a changelog)CHANGELOG.txt has to be updated to reflect the new version number.
    • Automated unit tests need to be run and complete without failures.
    • The primary/major module functionality needs to be tested manually.
  • Use drush release-notes to create the release notes for the release node on drupal.org, as described in the guidelines for commit messages.

Help improve this page

Page status: No known problems

You can: