Branching Model & Workflow
We use a very simple branching model, with
develop for active development, feature branches for implementation work and
master for tagged release-ready. It’s simple enough not to need additional tools beyond
sequenceDiagram develop->>feature/«NAME»: Create feature branch. feature/«NAME»->>feature/«NAME»: Commit mentioning issue. feature/«NAME»->>develop: Merge request and review develop->>master: Release via merge request. master->>tag «vX.Y.Z»: Tag release for deployment tag «vX.Y.Z»->>tag «vX.Y.Z»: Auto build of release output.
developbranch is the long-running branch.
masterbranch is used to tag releases. By keeping these separate we can make emergency hotfixes to master without merging in develop.
- Code changes should be made in feature branches, branched off
develop. The name of the branch should start
feature/and have a relevant name.
- Once the feature branch has been merged into
developit should be deleted. We should have no long-running branches except
- Before starting work make sure you’ve pulled the latest
- Don’t be afraid to make small changes to your feature branch and push them. The merge will usually be squashed, so the diff will show as one single change.
- Look at the CI results as you push feature branches. This will avoid a nasty shock later on.
- Prefix your merge request title with ‘WIP:’ if it’s not ready for review. Remove this prefix when it’s ready.
- Merge Request should be against the
Step by step
- Ensure the change you want to make is represented by one or more specific issues. That could be a User Story, e.g.
user_stories#5or an issue on the same repo as the code, e.g.
- Check out the
developbranch and pull to ensure you’re up to date.
git checkout develop
git pull origin develop
- Create a feature branch off develop for your issue:
git checkout -b feature/add-widgets
git branchshould tell you you’re on
- Make changes to the code. Commit as often as you want to your branch.
git add myfile.xyz
git add src/java/my/package
git commit -m "Add widgets for issue #5"
- Push as often as you want to your feature branch.
git push origin feature/add-widgets
- Create a Merge Request, asking that your feature branch is merged back to
master). When you push a branch GitLab will construct a ready-made URL for you which appears in the console. Or do it manually via GitLab interface.
- Assign the Merge Request to the reviewer.
- Reviewer will review, give feedback. You may need to make more commits to your branch and push them in response to the review.
- When the review is concluded, it will be automatically merged back to develop.
We may also welcome Merge Requests from developers in the community.
- Follow Code Review process. Don’t merge if it doesn’t pass.
- Merges should usually be from
develop. If needed, the feature branch can be rebased against
developvia the GitLab interface.
- Tick the ‘squash merge’ box so that the whole feature branch can be merged in one go. Take the commit message from the description of the Merge Request. Ensure that relevant issue numbers are included in the message.
- Once merged, go to the issue, review the acceptance criteria on the relevant ticket(s) per the Code Review process.
To create a release:
- Observe the latest tag. Use Semantic Versioning to determine the new version number, e.g.
- Write release notes for the version. Include a headline that starts with the version number and a summary. Underneath mention the changes, with links to issues.
- Create a Merge Request from
masterwith a merge describing the new version, including the version number. Wait for the CI to give the all-clear, then merge across. Don’t squash merges.
- Once merged, create the tag on master with the release.
- Wait for CI to build and package the Docker image into the repo’s Docker Registry.
- CI is used for:
- Compilation checks
- Test run
- Compilation and packaging (into WAR or Docker image)
- Static Analysis
- Most of this should run for all branches.
- Test reports should be available on the CI Artifacts page.
- Static Analysis in SONAR is triggered by CI, but you must go and look deliberately at the SONAR report to see the results.