Every development team has a particular way of working. However, over the years I have noticed that there are a few common practices that, once documented and agreed upon, can help considerably in the team’s productivity. This article aims to serve as a template for new and existing projects.
Assumptions
- The code is hosted on GitHub, BitBucket, or GitLab. What's important is that it supports pull requests.
- There is a ticketing system like Jira.
- There is a Continuous Integration tool that runs checks on pull requests.
Feel free to copy the following contents to an internal page in your wiki and start discussing and adjusting it with your team. It’s crucial that everyone in the team is willing to give these practices a go for a sprint and then evaluate and adjust during the next sprint retrospective.
The README and CHANGELOG documents
Each repository must have a README file and may have a CHANGELOG document.
The README describes the project’s nature, lists requirements, and contains installation instructions. This document should contain everything that a developer needs to set up the project locally. If you are looking for a Drupal 8 specific one, here is an example.
The CHANGELOG is the living Release Notes document that allows anyone (developers, product managers, etc.) to understand exactly what changes are affiliated with a specific version of the project. This document is used when creating new releases to describe how should other teams update their current installations.
Working with repositories
It’s useful to receive notifications every time that someone makes changes in a repository. We encourage you to subscribe to pull requests in order to start learning from everyone's code by clicking on the eye icon at the top right corner of each repository's homepage:
Make sure you have a GitHub account with an SSH key. You can add your SSH key here and, after doing that, you can share it with the team by appending .keys to your profile, like this.
Setting up your environment
Each project is different, so look at the repository’s README for instructions on how to set it up. If you find a repository which does not have a README, use this one as a template.
Setting up your editor
You can use any editor to work on projects, but the one that offers the best integration with Drupal 8 at the moment is PHPStorm. Please take a few minutes to adjust PHPStorm to work with Drupal by reading this guide.
Working on a ticket
Each ticket should have its own branch or branches. A branch name should be prefixed with the ticket number and a one or two-word description (for example, PROJECTNAME-123-foo). Here is how you can do it:
cd /var/www/projectname
git checkout master
git pull origin master // Merge the current master into your branch.
git checkout -b PROJECTNAME-123-foo // create and switch to a new branch 'PROJECTNAME-123-foo'
Once you are ready to push your changes, commit them to the branch with the following commands:
git status // Shows your changes.
git add [file] // Add any new or modified files. Supports patterns.
git add --patch [file] // Better yet, review changes and stage your hunks.
git diff --cached // Shows what is about to be committed. Review it carefully!
git commit -m "PROJECTNAME-123 Description shorter than 50 characters"
Aim to make small commits which you can describe easily in your branch. The Erlang project has a good guide for writing good commit messages. If you want to add further info to the commit message, skip the -m parameter and use the default editor to set the title and the description of the commit message.
If your pull request alters the installation process or requires additional steps during the updating process, then adjust the README and CHANGELOG files accordingly.
Writing and updating tests
Bug fixes and new features will be easier to peer review if the project's tests pass and the new code is covered by the tests. To get an idea of what sort of tests you may find, check out this article.
Ok, ship it!
Once you have completed the above section, push the branch to Github:
git push -u origin PROJECTNAME-123-foo // pushes your branch to the origin repository.
PROJECTNAME-456 Fix video uploads only allowing mp4
Post a link to the pull request in the respective ticket and set it's status to "Needs Review" in order to track progress within the sprint.
Peer reviews
The rule of thumb of peer reviews is that nobody can push to master branch. Everything should happen in pull requests which are reviewed and merged by the rest of the team.
After creating the pull request, prepare it for code review by following this guide. Once the pull request is ready for review, add reviewers to it through the web interface. Here is an example:
When merging a pull request, follow the git standards with a short one-line message, a blank line, and paragraphs if needed. Here are two sample merge commits::
[#pr-number] PROJECTNAME-123: Summary of the work being merged
PROJECTNAME-123: Summary of the work being merged #pr-number
Finally, if this pull request completes the Jira ticket, then open it and change its status to the next one, which normally is "In QA", if you have a QA team, or "Done" if not.
How to create a release
If you are distributing code to be deployed by other teams, then your team needs to keep a CHANGELOG which evolves along with the code. Review the section "The README and CHANGELOG documents" for an introduction.
Once the sprint has completed, it is time to create a release. Here are the steps to follow:
- If there is Continuous Integration, check that all tests pass and that there is the same or higher coverage that by the end of the previous sprint. If not, request the development team to fix this.
- Clone the repository where you want to create the new release.
- Create a new branch where you update the module's CHANGELOG by setting a version number at the top. If the module does not have a CHANGELOG file yet, create one using the example further above as a template.
- Developers indicate the level bump needed for each change by indicating it with the word "PATCH", "MINOR" or "MAJOR". This takes into account semantic versioning. So, depending on the changes that this release includes you increase either the PATCH, MINOR or MAJOR number for the next version.
- Once the pull request has been approved by the team, merge it.
- Create a tag:
git tag -a [VERSION] - Enter a description of what is being released on this tag.
- Push the tag to the repository:
git push origin [VERSION].
Note: If you need to double check anything stated in the CHANGELOG while preparing the release, you may use the following command to retrieve all commits since the last release:
git log --oneline --reverse --first-parent <insert last tag version here>.. | cut -c 9-
git log --oneline --reverse --first-parent 1.0.0.. | cut -c 9-
Ticket review guide
Here are a few tips for both sides: the individual working on the code and the people reviewing the pull request.
For the pull request authors
- Make sure that the checked in code does what the ticket specifies.
- Use code sniffer to check and fix violations against Drupal’s coding standards.
- Add comments on the code as you see fit. This is useful not only for maintenance but also for peer reviewers.
- Make sure that your set of changes are covered by reasonable PHPUnit or Behat tests.
- Write a summary of what the code does and other related info such as screenshots. Include manual testing instructions if needed.
- If there is Continuous Integration, verify that all jobs pass.
For the reviewers
- Verify that all the jobs executed by the Continuous Integration tool are passing. If there are failures, inspect the logs and notify the pull request’s author.
- Check that the code is easy to follow, respects Drupal’s Coding Standards, and is documented.
- If there are no tests, consider suggesting how they could be written.
- Look for performance and security risks. If you need tips, this guide offers great help.
Further tips can be found at The Peer Review How-To guide.
Acknowledgments
This guide is the result of working with the following clients, which we thank deeply:
- The Biology Information Technology team at Iowa State University.
- The Draco team at Turner
- The MSNBC team at NBC Universal
Plus, the following folks at Lullabot: