git for version control on all projects and host the repositories on GitHub.
Our branching strategy
We keep it simple and use GitHub’s flow:
- Create a new branch from
- Add your changes on this branch
- Open a pull request and request reviews
- Communicate your changes
- Merge into
On most projects, creating or pushing to a branch will create preview deployments. This way, changes can be reviewed by simply opening a link.
Furthermore, we have a
production and a
staging branch. When new code gets merged into them, a deployment will automatically be triggered.
How should I name branches?
We currently don’t have a particular naming convention. This is because we delete all branches after merging and will have their changes documented as pull requests on GitHub.
This means that there is no need to prefix them with e.g.
fix. However, this is your decision.
When should I create a pull request?
Up to you! The earliest instance would typically be when you’ve created a new branch with new commits. The latest could be when you want or need feedback on your code.
When should I request a review?
This is hard to define. Typically, we follow these general milestones:
- after you’ve proofread your PR
- after you’ve tested it on the feature branch/preview deployment yourself
- when you think you’ve implemented all requirements
What does the review process on GitHub look like?
- Reviewer leaves a comment
- Author fixes the code
- Author re-requests review or comments on fix
- Reviewer resolves comment or approves PR
How do I deal with branches that are not based on
Generally speaking, this should be avoided whenever possible. From a product perspective, there are ways features can be implemented independently from each other.
When creating new branches, make sure to base them on
main. If your branch depends on changes of a different branch, try to get it merged first by reviewing or working on its pull request or come up with a solution that doesn’t depend on it. The concept of feature flags may help with this.
If there’s no way around depending on a different branch than
main, there are a couple of rules you can follow.
main ← first_branch ← second_branch
When creating the pull request for
second_branch, set its base branch to
first_branch. This way, only the new changes are shown in the diff. Additionally, add a bold sentence to the top of the PR description, that highlights that the branch doesn't depend on
If your branch gets approved, but
first_branch hasn’t yet, wait for it to be merged first. Make sure to set the base branch to
main again before clicking the merge button. GitHub usually does this automatically.
Exception:In case your changes are very small you can also merge your branch into
first_branch. However, all of your changes will be added to its PR. This can lead to people reviewing your code twice, so usually we tend avoid this.
When should I review pull requests?
We typically do reviews during fixed times of the day in order to be mindful of everyone’s time.
- first thing in the morning
- right after lunch
What is a good size for pull requests?
This can vary a lot and particularly depends on "how big" a feature is. The smaller the better, but splitting up logic should be avoided. Most of our projects are organised in components – a general guideline would be to try to have one component per pull request.
What should I look for when reviewing pull requests?
Please have a look at our pull request guidelines.
The best way to review CSS is to open the preview deployment and test its functionality and adaptability for different viewports and content.
When it comes to the code itself, check if it adheres to our CSS architecture.
Here is an excerpt:
- check if class prefix is the component name
- no tags are used as selectors
- styles of other components are not overwritten
In general, we try to find changes even if they might require updating the documentation. We ask questions about confusing or complex code. This can be done as a comment on GitHub or in person.
How should I merge branches into
GitHub offers three options: merge commits, squash merging and rebase merging. We use merge commits, as they don’t erase information (e.g. individual commits or messages). A clean view of the
main branch can still be achieved by filtering the commit history by commits starting with "Merge branch". If you have the required access rights, feel free to disable the other two options in the repository settings.