How to contribute to Drupal

Someone asked my this personally and I thought, instead of answering directly, I could write down what I know in a blog post. Note that this is my personal opinion, you might disagree and are welcome to provide suggestions in the comments.

---

So you started using Drupal or are already using it for quite some time to create websites. And you want to contribute something back because you can use Drupal and all these modules for free.

Some seem to think that contributing = "Uploading a custom module" and everything else doesn't count. But that's not true, there are already many thousand modules for almost everything, don't create new projects if an existing one already exists and just needs to be improved a bit to do what you need.

There are many possible ways to contribute something back, some don't even require any special skills, quite the opposite even!

Here is the official documentation about contributing: http://drupal.org/getting-involved

You can find information about the used tools and infrastructure like IRC, issue queue, how to work with patches and so on.

Documentation

Start by reading this: http://www.lullabot.com/articles/drupal-best-practice-document-your-way-...

To write documentation, you don't need a lot of technical skills, yo should be able to write english that is understandable by others though. It doesn't need to be perfect, others can always improve it or correct errors. But someone needs to start writing it.

Many contributed modules are lagging behind when it comes to easy to understand, user-facing documentation. There might be nothing at all or maybe it's outdated and for an old version of the module. You can easily see if a module has some (official) documentation by checking if there is a "Read documentation" in the Resources category on the right side. If there is, read it to see if it is still correct, fix it if not. You do not need any special permissions to do that.

If there is no documentation at all, you can start fresh and once you have something, you can contact the maintainer of the module by creating an issue so that he can review it and add a link to it from the project page. Documentation can be basic information about what the module can do, how to do configure it or it can be detailed information on how to customize the module using hooks, Rules, Views and so on.

See also http://drupal.org/project/documentation

Help maintaining the issue queue

Large projects often have many, many open issues. Quite a few of them are possibly duplicates. Look through them, if you find duplicates, close on of them (the one with less information) as "closed (duplicate)" and link to the duplicate issue. See also below for helping with tracking down bug reports, try to answer support requests and so on. Check if a requested feature already exists and explain on how to use it.

Tracking down reported bugs

Many of the large contrib projects (and core obviously too!) have dozens or even hundreds of bug reports. Some of these only have very little information given or depend on specific configuration or other modules installed on the site. Look for bug reports which have a "active" (or "postponed (needs more information") status and few or none comments. Here is a list of things you can do with them:

- Try to reproduce the issue based on the provided information. If you can reproduce the bug, provide detailed steps and describe your configuration and other modules installed on the site where you reproduced it.
- If you can't, ask for the above (steps to reproduce, installed modules and so on)
- If it's not a bug but just needs something configured differently or another module or ... explain that, switch the issue to "support reqest" and set it to "fixed". Even better, create a documentation page and point to it in the issue.
- Reclassify the issue as necessary, maybe it's not a bug but a missing feature, or not critical but only a normal bug. (See http://drupal.org/node/156119 and http://drupal.org/node/45111 for information about what status/priority means what)

Review and test patches

Say, a maintainer or someone else uploaded a patch to fix a bug or implemented a desired feature. What is required now is that someone does test and review that patch to make sure that the bug is really fixed, the feature properly implemented. And second, that no new bugs have been introduced by the changes. A more detailed description of these two steps follows below.

If both parts have been done (by you or by multiple persons), mark an issue as "RTBC" (Reviewed and tested by the community". The definition of done depends on the issue/context. A simple bugfix to remove a php notice or warning message might not need more than some basic testing. A patch written by the maintainer himself might not need a detailed review (I'm sure most would love to get one though!). A complex new feature might require extensive testing and reviewing.

And when you don't find anything during testing and reviewing, write that down too, otherwise the maintainer doesn't know that you *did* test the patch ("I tested X, Y and Z with the patch and did not find any issues.").

Test

Required skills: Know how to apply a patch (There are links on that page on how to apply on windows or use git)

This basically involves downloading the patch, applying it and then test everything you can think of to verify that the patch works as advised. Some suggestions:

- Is the reported bug fixed?
- Are there other steps that can still lead to the same bug?
- Are there any new bugs introduced by this patch? (If you discover unrelated bugs which you can reproduce with and without the patch, open a new issue and link to it)
- If there is a new feature, does it work?
- If there is new interface text (for example, a setting), is it understandable? Could it maybe be improved or would a description or help text be useful? Provide actual suggestions if you have any!
- Are there usability or accessability issues?
- Does it work, but maybe there would be a better (whatever that means, for example easier to use) way. Write that down. Maybe the patch author/maintainer hasn't thought of that and likes your suggestion or maybe there is a reason for not doing it like you suggested. But by writing it down, you can discuss and and maybe document somewhere why it is like that.
- Maybe an additional feature on top of that would make it twice as useful. Discuss with the patch author/maintainer if that could be implemented in the same issue or a follow-up issue might be more appropriate.
- Maybe the issue is about fixing a bug, but someone provides a patch that also fixes another bugs or adds a new feature. Note that and ask if that is ok or should be handled in a separate issue. See http://www.webchick.net/please-stop-eating-baby-kittens
- Whatever you can think of..

This is a very important step, don't hesitate to write down suggestions, ideas, bugs you found and so on. But don't expect that anything will be implemented/changed either. Obviously, it depends on the issue, if it is a trival patch that just fixes a Notice, most of the above might not be necessary. And it also depends on the maintainer, but I myself love detailed testing feedback because it tells me that someone actually tested and looked at the patch. As an example, see this comment from BenK. He has done dozens of tests like this one and his help has been invaluable during the process of getting working versions of Privatemsg, Userpoints and other modules out for Drupal 7.

Review

Required knowledge: As much knowledge of Drupal, PHP, ... as possible, but not that much is required for basic reviews.

This is the technical part of the testing process. Dreditor is a very helpful tool for this as it allows to do detailed reviews of a patch directly in your browser (Firefox or Chrome), strongly suggested! Some things to check in a review:

- Does the patch follow the Drupal coding standards? For example using of spaces instead of tabs for indentation, function naming and much more. I suggest to at least skim over the linked page before starting to do reviews to at least know *what the standards cover (You can read the details when you have to).
- Does it follow the security guidelines to protect against SQL Injection, XSS and so on.
- Is there apidoc for new and changed functions? (for example, if a function argument changes, has the documentation been updated)
- Is there inline documentation? Does it follow the standards (see above, e.g. wrap at 80 chars, start with "//[space][Big inital]...", proper english, ...). Are there complicated parts which should be explained?
- Is the code using the API functions correctly?
- Could some parts be simplified by using existing API functions?
- Do you spot any obvious errors just by looking at the code?

Again, this depends on the on the patch, a simple one line patch does usually not need a detailed review (but you should still look at it and report *if* there is something). Also, you do not need to review everything, just doing a part of it can already be a huge help. Just state what you did so that the maintaner knows that you haven't reviewed everything ("I reviewed the coding standards of the patch and it looks good/found this:").

Also, the more you do it, the more used you'll get. I wrote and reviewed hundreds of patches for Drupal core and contributes modules and coding standard violations jump at me when I just skim over a patch. Also, reviewing patches will increase your knowledge of PHP and Drupal, you'll learn new API functions and so on.

Creating patches

So you actually want to write code yourself and provide that as patches. I'll not go too much into the details on this one, just a few hints:

- First, you need to learn the workflow, I suggest doing that by fixing some trivial bugs (E_NOTICE errors, documentation fixes). Every project has a very helpful "Git instructions" tab with detailed instructions on how to check it out with Git and create a patch against it. Make sure you follow the coding standard, write secure code and so on (see Review above). Then, create an issue if there isn't any yet (search first!) and then upload your patch. Wait for feedback and update your patch if necessary.

- Then you can try to fix some more complex bugs or implement basic features following the same workflow as before.

- Don't give up if nobody looks at your patch during a few days. Review other patches/issues in the same issue and ask for a review of your own patch in return! Remember that most maintainers don't just sit around and wait for issues which they can fix or/or review. Most of them maintain their modules in their free time.

- Also don't give up when you get a lot of feedback that needs to be updated in your patch. After working on core for years, I can be very picky about coding standards and so on, and many others are likely similar. After all, most maintainers (I do, if others don't, then provide patches to my modules instead! ;)) love it when users don't just ask for features or report bugs but provide patches too and will gladly answer any questions.

- Be prepared to write tests for your new feature, see http://blog.worldempire.ch/story/writing-automated-tests-drupal-7. Even better when you provide them from the beginning! Some projects also have automated testing enabled which means that your patch is atomatically tested against the existing tests.

That's it for now, looking forward to comments!