This is a set of rules that I have been gathering in the past few years, which work well for most of the projects I worked on with small teams of 3-8 people. These guidelines are heavily based on the angular.js/DEVELOPERS.md document on GitHub. This is not about GitFlow, I think it is too complex and goes against fast development cycles. Build good and reliable CI/CD pipelines to be able to deliver faster, use canary releases whenever possible.
Always create a new branch from an updated “master” branch. The branches should have a short life (no more than 2 days) and have a very determined objective. Once the objective is reached, a Pull Request (PR) should be created to merge the branch to “master”. Once the branch is merged, it should be deleted. Always merge to “master”.
The branch names are not that important in very small teams, but when the team is bigger or work remotely, a pattern for the branch names is also good to follow. Here is a suggestion:
Some tools like Sourcetree from Atlassian pick the
/ from the branch name and splits the name in their GUI,
so you can see the different types of branches as in different folders.
- feat: a new feature,
- fix: a bug fix,
- docs: documentation only changes (in or out of the code),
- tests: new tests or fixes in tests,
- refactor: code change that neither fixes a bug or adds a feature,
- style: code changes that neither,
- chore: Changes to the build process or auxiliary tools for the project maintenance,
- perf: A code change that improves performance.
This is optional, but is good if the purpose of the branch is too complex or if you follow a Scrum development process.
Here we follow a very specific pattern in order to be able to parse the commit messages to automatically generate a change log for each release in a CI/CD process and also semantic release version bumps with tools like semantic-release (available for Node.js and Python).
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>
The header is mandatory and the scope of the header is optional. Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
Theis optional, but if you use it, just as in the subject, use the imperative, present tense: “change” not “changed” nor “changes”. The body should include the motivation for the change and contrast this with the previous behavior.
The Pull or Merge Requests (PR) are used to share with your co-developers the code changes you did in your branch and ask them to review it. Here we always do a PR from your branch to the ‘master’ branch. In a PR, your colleagues will have a view of the differences between the branches and the commits. You must also add a title and a description. The title should be sufficient to understand what is being changed. In the description you should: - make a useful description, - describe what was changed in the pull request, - explain why this PR exists, - make it clear how it does what it sets out to do. E.g: Does it change a column in the database? How is this being done? What happens to the old data? - you may want to use screenshots to demonstrate what has changed if there is a GUI involved in the project.
Pull request size: It should be small. The pull request must have a maximum of 250 lines of change. Feature breaking: Whenever it’s possible break pull requests into smaller ones. Single Responsibility Principle: The pull request should do only 1 thing.
With this setup your CI/CD pipeline would: 1. run your checks and tests for every push to a PR and every merge to ‘master’, 2. run a deployment to your test environment every merge to ‘master’, and 3. enable a manual deployment to your production environment for every merge to ‘master’. This deployment should trigger a release first, with automatic version bumping and change log generation. Bitbucket-pipelines supports this.
Remember: git is a collaboration tool, not a reporting tool.
- The anatomy of a perfect pull request – Hugo Dias – Medium
- Conventional Commits
- Gitflow Workflow | Atlassian Git Tutorial
- angular.js/DEVELOPERS.md at master · angular/angular.js · GitHub
- GitHub - semantic-release/semantic-release: Fully automated version management and package publishing