What Contributing to Drupal Taught Me

The useful part is in the issue history

Some of my open source work is in Drupal's issue queues: patches, review comments, revisions, and discussions about how a change should behave. I have also co-maintained modules and spoken about Drupal. My Drupal.org profile (opens in a new tab) links that work together.

A list of merged changes shows what got accepted. The discussion before a merge is often more useful to someone learning how to contribute. It shows the questions a maintainer asks and the details that need attention after the code appears to work.

One Ultimate Cron issue is a good example. It was a specific piece of maintenance work, with a public record of the patches and review.

A patch improves through review

In Ultimate Cron issue #2728873 (opens in a new tab), the goal was to allow cron jobs to call services and move queue processing into a service. I submitted patches; Berdir reviewed them. The review covered the callback format, naming, dependency injection, unused imports, and documentation. One patch also failed testing and needed another revision.

The change was eventually committed with credit to both of us. The record makes the collaboration visible: implementation, questions, cleanup, and a later patch update before the merge. The final patch included both the implementation and the changes prompted by review.

I take a practical lesson from that history. Working behavior is one part of a contribution. The maintainer also needs code that fits the project and can be understood by the next person changing it. A clear name or useful comment can be worth discussing even when it does not change the immediate result.

When reviewing someone else's patch, explain the concern behind a request. “This callback needs to resolve through the container” gives the contributor something to reason about. A bare instruction to rewrite it leaves them guessing at the project's expectations.

Start with a problem you can reproduce

Choose a project you use and an issue you can describe precisely. Familiarity with the user-facing behavior is useful even if the internals are new to you. A small reproduction gives you a concrete place to begin reading the code.

Before writing a patch, read the contribution instructions and recent discussion. Check whether someone is already working on the issue, whether the problem still occurs, and whether the proposed change fits the project's direction. For a feature or a large refactor, agree on the approach before investing heavily in implementation.

Suppose a form rejects a valid date. A useful report identifies the version, configuration, input, expected result, and actual result. Reduce it to the smallest case you can reproduce. If you cannot yet fix it, that report still saves the next person time.

Documentation has the same requirement for evidence. Run the setup instructions in a clean environment. If a step is missing, record what failed and the command that resolved it. That is a more useful first contribution than a broad rewrite of documentation you have not used.

Make the change easy to review

Keep unrelated cleanup out of a bug fix. A reviewer comparing a small behavior change with a large formatting diff has more work to do and more opportunities to miss a problem. Follow local conventions even when you would choose differently in your own repository.

The description should let someone verify the change without reconstructing your investigation. For the hypothetical date bug, a short description might look like this:

An illustrative patch description

The date field rejects 2024-02-29, although 2024 is a leap year.

The fix checks the day limit using the submitted year.
Added regression cases for 2024-02-29 and 2023-02-29.

Verified: the first date is accepted; the second is rejected.

Include those checks only if you actually ran them. If you could not run part of the test suite, say which part and why. That lets the maintainer assess the remaining work without guessing.

Treat review as a conversation about the change. Ask for clarification when a request is unclear. If you disagree, describe the behavior or maintenance cost you are concerned about. When you upload a revision, say what changed and which questions remain open.

A maintainer may decline a working patch because its support cost is too high or it conflicts with the project's direction. That does not mean the investigation was wasted. A reproduction, test case, or documented limitation may still be useful to the project.

Share what helps someone do the work

My Drupal talks have covered real-time notifications, profiling and debugging, and building a multimedia site. The recordings are still available:

These are older talks, so treat their setup and API details as historical. A recording is also useful as a record of the problem being discussed, without claiming that every technique remains the right choice for a new project.

For a talk or tutorial of your own, choose a problem the audience can recognize. Show the failing behavior, the investigation, and the change that resolves it. Explain the constraints. If a demo depends on a particular version or configuration, publish that alongside it.

There is plenty of useful work that does not need a conference slot: confirming a bug, testing a patch, explaining an error message, or answering a question with a reproducible example. Choose the form that helps the person who is stuck.

Be honest about maintenance

Publishing a project means people may start depending on it. A small tool needs a clear purpose, working installation instructions, a license, and a way to report problems. It does not need an elaborate governance structure before anyone has used it.

State what you can support. If the project is an experiment or you only maintain it occasionally, make that visible. Avoid promising release schedules or long-term support that you cannot sustain. Accepting every feature request can leave you with a project that no longer fits the time you have.

The same applies when joining an existing project. A module maintainer takes on release decisions and follow-up work as well as coding. Before accepting the role, understand the backlog, the supported versions, and who else can help. If your availability changes, tell the other maintainers so they can plan around it.

Choose a contribution you can finish

You do not need a month-long plan to begin. Find one problem, establish what is known, and make the next step easier. That might be a patch. It might be the missing detail that lets someone else write one.

I would start with a dependency you already use and a task small enough to follow through on review. A contribution is more useful when its author can explain it, respond to questions, and help get it into a state the project can maintain.