Last updated 17 November 2015.

Maintaining a project on means more than just uploading your code. This section of the documentation covers best practices for being a successful maintainer of a contributed project (such as a module, theme, installation profile, etc.).

Project documentation

Since you've decided that your project is worthy of releasing to the Drupal community for general use, it is a good idea to put some thought into documenting your project. There are several forms project documentation can take; your project should include several of them:

  1. README.txt - This will be included with your project's distribution (tarball). It should include a short description of what your project does, and provide further information to the person who is installing your project. It should include any special instructions or considerations that need to be addressed at installation or configuration time.
    Example. See also README files
  2. INSTALL.txt - This is an optional file that can be used if the "readme" file is too large or complex. It would concentrate on the installation tasks.
  3. Project page - This is a succinct description of your project. The first paragraph or two should be a short description of your module, theme, or installation profile's basic functionality and why people would want to use it. After that short description, insert the teaser end tag ("<!--break-->") or click on "Split summary at cursor", to define the "teaser" that will be shown when people are searching for modules, themes, etc. The rest of your page can include more details of what your module does, what your theme looks like, your project's dependencies, related modules, what makes your module/theme/profile different from other similar ones, compatibilty concerns, links to demo and documentation pages, who sponsored the development, etc. But you don't have to have a complete installation and usage guide on this page -- that is better done in the README or a documentation page.
    Example. See also Tips for a great project page.
  4. CHANGELOG.txt - This file will be included with your project's distribution. It should contain all fixes, changes, and additions between official releases of your project. It helps users and developers who upgrade to a new version to understand what has been changed or improved recently. See Commit messages for best practices on maintaining this file.
  5. Documentation page - Your project can have its own page or section in the Drupal Docs. A documentation page should repeat and expand upon information from the "readme" and "install" files -- it should include information on how to install your project, how to use your project, and any pitfalls users might encounter. Supplying a few use cases can help a potential implementor to get a good idea on how your project can be used on his/her site. Once you have created a documentation page (node/add/book), add a link to the page in the "Documentation" section of your project page (this is a field on the Edit screen for your project, under Resources).
  6. Security announcement - There will be more on why you might need this on the next page.

Coding Standards

It is recommended that you install and use the Coder module. In addition to making sure you've adhered to the Drupal coding standards, this module also can give you performance hints and Drupal version upgrade advice.


Drupal has a diverse and international community. Many of your potential adopters are not going to speak English or want to have their sites in English. If your project is valuable to someone with a different language, they may very well step up and provide you with translations for your project on

Information on how to set up your module so it can be translated can be found in the Localization API section of the Develop for Drupal documentation. If you use the localization API properly, and release tagged versions of your modules (vs. continually changing development snapshots), your project will be available for translation automatically on

Previously,'s git was used to maintain translation templates and translations themselves. Now all translations are maintained on

Further reading:

Hosting code at

Contributors are strongly encouraged to host at rather than elsewhere (GitHub, BitBucket, your personal site, etc.). Each project (a contributed theme, module, feature installation profile or translation) needs to be maintained in the contributions repository. If you are not using the infrastructure, you cannot setup a project page on nor can you offer your module for download at Please note that all code which is committed into a Drupal repository must be covered under the terms of the GNU General Public License, version 2 or greater; the same as Drupal itself.


Consider whether there is an opportunity for you to collaborate on existing projects rather than compete by starting a similar one. One way to help avoid this is to post your module idea to the Contributed Module Ideas group.

See also Joining forces with others and co-maintaining projects and Best practices for co-maintaining projects.

Other considerations

You may also want to read Dries's blog post about responsible maintainers and the documentation page about Commit messages - providing history and credit, as well as the other pages in this section of the documentation.


EliseVanLooij’s picture

Just read the announcement of the new Drupal Code of Conduct and was wondering whether it would apply to dealing with new contributors as well. When I applied for a CVS account, I just received a 'sorry' and a link to a page which listed issues that might cause a module to be rejected. I probably should have printed it out and thrown darts at it to guide me in the process of becoming a better drupal'er, but instead I opted to follow rule 5 of the DCOC.

TomSherlock’s picture

I thought was migrating to Git.
Should potential module contributors open a git account as well?

mgifford’s picture

As much as we want to have developers use best practices, there should be a reward for doing so. I've developed some code but mostly ideas about how this could be done with Contributed projects

Looking for feedback as there will always be ways to improve it.