Contribution and Client Projects: Part Two

Contribution and Client Projects: Part Two

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.

Project Version

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

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”.

Needs review

Contribute a full project

Workflow

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 :)

Drupal 8.7 started the deprecation work and 8.8 will define the full deprecation list.

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.

Developer toolbox

Here is a brief recap of the tools that might help you while contributing.

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.