Before we start, let’s just remember two things:
- Contributing is easy and not only for senior developers. Even the smallest contribution matters, this is the summation of those contributions that make the community and the codebase strong.
- You are part of a community. A great way to get started with contribution is to find a mentor at a Drupal event, and there is always someone ready to help on the Drupal Slack #contribute channel.
The Drupal.org issue queue
While working on client projects, you might encounter core or contributed bugs or you may need a new feature.
Chances are that this issue has already been discussed in the issue queue that covers the Drupal core or all projects, including contributed. If your issue is not yet in the queue, use the issue template summary to file one. You might also check this page about creating good issues.
The main process for an issue is Active > Needs work > Needs review > Reviewed and tested by the community (RTBC) > Fixed > Closed.
When the issue is fixed or closed, the project maintainer will include the changes in the codebase (dev branch) and will most probably wrap it with several other closed issues into a release. Read about the semantic versioning model.
If you need the patch before the release, you can include it in your client project with Composer.
If the issue has not been reviewed/tested yet, just make sure that you are using the right version of the Drupal core or contributed project.
From there, the main tasks you can contribute to as a developer are:
- When the issue needs review: manual or automated testing
- When the issue needs work: re-roll or create a patch.
We will summarize the process of creating a patch below:
You can also find novice issues and continue your reading with the Novice code contribution guide and the New contributor tasks: programmers.
Create a patch
Now that the codebase is on GitLab, there was a proof of concept for fixing a trivial issue on Drupal.org using only the issue queue and GitLab.
For most cases, you still need to use the following flow.
Create the patch from the issue branch
The branch is the one from the Version meta on the issue.
Drupal core: https://www.drupal.org/project/drupal/git-instructions
Contributed project: click on the Version control tab
Follow then the git instructions on the page to create the patch, basically:
Create a new branch: git checkout -b [patch_branch]
Make your changes then review them with git diff
Add your changes with git add
Output them as a patch file
git diff [base_branch] > [description]-[issue-number]-[comment-number].patch
Submit the patch
Once your changes have been made, upload the patch on the issue, then include a comment that describes your solution and everything that will facilitate the review, like screenshots or interdiff.
If there are unit tests available, request a test for your patch, then set the issue status as “Needs review”.
Contribute a full project
There are several ways to go, but this procedure works well for us while working for client projects on a module (or theme) that could be contributed.
The first iteration is built straight on the client project repository with a generic name until the related ticket testing is finished, so that:
- reviewers can check all the code in one place and most likely they already have an environment running with exhaustive data for testing.
- if the ticket is reopened, the process is simplified (there is no release to maintain or Drupal.org process involved).
Using a generic name still favours reusability among other client projects if we decide that it will not be contributed on Drupal.org yet. We can then isolate it in a dedicated repository, then include it via Composer.
Publish it on Drupal.org
1. Make sure that your project contains the following files
- The composer.json file that contains the project metadata + system requirements (e.g. ext-json), third party libraries (e.g. solarium/solarium) and Drupal dependencies (e.g. drupal/search_api).
- The [your_project].info.yml file with the Drupal dependencies, prefixed by their namespace (e.g. drupal:node or webform:webform_ui).
- A readme with the use case, the dependencies, related projects (and how this one differs), a roadmap if the project is not feature complete.
2. Fix and check coding standards
- Autofix with phpcbf: phpcbf --standard=Drupal --extensions=php,module,inc,install,test,profile,theme,css,info,txt,md /path/to/project
- Check what needs to be fixed manually: phpcs --standard=Drupal --extensions=php,module,inc,install,test,profile,theme,css,info,txt,md /path/to/project
3. Create the project page
Most likely, it will be a Module or a Theme: https://www.drupal.org/project/add
Give it a name and a machine name.
Add the key points: project classification, description (the project readme is a good start) and organization. Make also sure to add other maintainers if you are working in a team.
4. Create a first, unversioned, dev release
- Create a dev branch (e.g. 8-x-1.x) and push the code
- Follow instructions on the Version control tab.
- Not mandatory, but it is recommended to create a clean installation with the latest release of Drupal so we’re sure about 2 things: all the composer based dependencies are resolved properly and there are no side effects caused by the client project.
- At this stage, other developers might include your code in the project with composer require drupal/your_project:1.x-dev
- On your client project, as there is no semantic version release yet (e.g. 8.1.0), it is a good habit to add the commit hash so you make sure that you keep control over the codebase that is actually used: composer require drupal/your_project:1.x-dev#commit
5. Create intermediate versioned releases
When the development is ready, you might create alpha then beta releases.
Beta releases should not be subject to api changes.
- Check out the latest dev branch commit: git checkout 8.x-1.x
- Tag it: git tag 8.x-1.0-alpha1
- Push it: git push origin tag 8.x-1.0-alpha1
- Create the release and document it. This article from Matt Glaman provides great information about creating better release notes.
6. Create a stable versioned release
When there are no open bugs and the project is feature complete, a first stable release will tell site builders that the module is ready to be used (e.g. 8.1.0). Follow the same steps as 5.
7. Apply for permission to opt into security advisory coverage
Follow the security review process.
8. Create a new major release
If there are backward compatibility changes, creating a new major release (e.g. 8.2.x) will indicate site builders and developers that there are BC breaks.
Read more with Best practices for creating and maintaining projects.
Be prepared for Drupal 9
TLDR; Drupal 9 should be released in June 2020. The first version will be about removing deprecated APIs and getting new versions of third-party libraries (Symfony 4 or 5, Twig 2, …). So, if a Drupal 8 project does not use deprecated code, it will work in Drupal 9 :)
Code contribution is needed there as well: on the core with issues like deprecating legacy include files, or by helping contributed modules to be Drupal 9 ready and fixing contributed modules Drupal 9 compatibility issues.
Codebase analysis tools
Several tools are here to help if you are contributing to issues or maintaining a project.
The upgrade status module scans the code of the contributed and custom projects you have installed, and reports on any deprecated code that must be replaced before the next major version.
Drupal-check, a static analysis tool based on PHPStan, will check for correctness (e.g. using a class that doesn't exist), deprecation errors, and more.
Further read about Drupal 9, how to prepare for it and analysis of top uses of deprecated code in Drupal contributed projects in May 2019.
Here is a brief recap of the tools that might help you while contributing.
- Drupal console
Code generation, debug and other helpers.
- Drush commands
This site lists Drush commands, by version.
- Lagoon, DDEV, Lando
Docker based environments.
- PHP Code sniffer
Fix and report coding standards issues with phpcs and phpcbf.
- PHPUnit in Drupal 8
Run unit tests.
Browser extension that provides multiple applications/helpers for drupal.org.
- Drupal module upgrader
Start to port a Drupal 7 module.
- Drupal development with PHPStorm
Among other features, includes helpers to create and apply patch, integrates with run PHPCS, PHPUnit, ...
Other ways to contribute than code
There are more ways to contribute, even if you are not a developer, the Drupal community is looking for
Read more about contribution on the Getting Involved Guide.