Last updated August 6, 2014.
Maintaining a project on Drupal.org 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.).
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:
- 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
- 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.
- 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.
- 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.
- Drupal.org 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).
- Security announcement - There will be more on why you might need this on the next page.
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 http://localize.drupal.org/.
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 http://localize.drupal.org/.
Previously, drupal.org's git was used to maintain translation templates and translations themselves. Now all translations are maintained on localize.drupal.org.
Hosting code at Drupal.org
Contributors are strongly encouraged to host at drupal.org rather than elsewhere (GitHub, BitBucket, your personal site, etc.). Each drupal.org project (a contributed theme, module, feature installation profile or translation) needs to be maintained in the contributions repository. If you are not using the Drupal.org infrastructure, you cannot setup a project page on Drupal.org nor can you offer your module for download at Drupal.org. 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.
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.