This guide assumes you're familiar with terms like branches, commits, merge, revert. If you're unsure, please explore the Git learning resources we've recommended here.
How you write commit messages matters. Commit messages are used to make sense of what happened in your application, to answer questions like why was a certain change done in a certain way, etc. When used properly, commit messages provide an indispensable documentation resource. Because commits couple the contents of a change with its documentation message, it becomes never-stale documentation, potentially allowing you to forego less efficient documentation practices.
This recommended resource provides the seven rules of a great Git commit message, and so instead of repeating its content, we're highlighting the ones that matter most to us:
- Subject line
- Separate it from the body with an empty line, since that's how Git software, including GitHub, tells the subject line apart from the body
- Limit it to 70-characters-long, otherwise, software like Github will hide the rest of the title behind another click, making it harder to read
- Link to your project management tool. If you're using Jira, a common practice is adding the unique Jira issue ID to the beginning of the subject line, e.g.
SALTO-123 My subject line
- Body: explain what and why vs. how
- How is the technical change, e.g. creating a custom field, or adding a certain condition to a flow. How is captured automatically as the NaCl content of each commit, and therefore doesn't need repeating in the commit message
- What is a future-reader-oriented succinct description of what happened. It's a level higher than the technical details, usually a summary that helps the reader make sense of the change without having to make sense of the NaCl change (the how)
- Why provides the business context, the rationale and motivation for the change - the most critical piece of information sometimes lost forever when teams don't have a great relationship with their documentation solutions. For many teams the best way to capture the why is by linking the commit to a relevant Jira issue (or any other project management tool)
This topic has proven tricky to discuss, similar to the religious debate over tabs vs. spaces, since there is no objectively right way. Therefore, we're focusing on the questions you should consider as you and your team decide on your own standard practices.
Some people break a task down into very small parts, and commit each small part, while others complete the entire task and push it in a single commit. Some take a hybrid approach, where they develop in smaller commits, and once their task is done combine those smaller commits into a single commit.
Why commit smaller chunks frequently? Some people find it makes them more productive, since each commit marks a milestone of some work they got done. In addition, when collaborating with others on the same branch, more frequent commits can limit the probability and severity of merge conflicts (no one likes resolving merge conflicts).
Why fewer commits? Some find this approach much more readable to anyone with less context, and even more useful in debugging workflows, like trying to revert a buggy feature in production.
It's considered a popular best practice to make sure commits do not mix concerns. For example, if you're building a new feature AND fixing a bug, most would recommend pushing two separate commits: one for the feature and one for the bug fix. Why?
- Separating concerns makes debugging and reverting easier and less risky. Imagine wanting to revert a commit. that introduced a new bug, only to find out it also contained a fix for a different bug, meaning if you revert you'll bring back that old bug that should have been fixed
- Separating concerns makes for more readable commit messages, and thus a more readable project history and documentation
A Git Workflow is a recipe or recommendation for how to use Git to accomplish work in a consistent and productive manner. Git workflows encourage users to leverage Git effectively and consistently. Git offers a lot of flexibility in how users manage changes. Given Git's focus on flexibility, there is no standardized process on how to interact with Git. When working with a team on a Git managed project, it’s important to make sure the team is all in agreement on how the flow of changes will be applied. To ensure the team is on the same page, an agreed upon Git workflow should be developed or selected. There are several publicized Git workflows that may be a good fit for your team.
This guide focuses on the thinking behind our recommendations. The full workflow touches on tools and concepts beyond Git, so we've created a dedicated guide you're encouraged to try out.
As mentioned above, there is no universal right choice. While we stand behind our recommendation, it's important to take it as a starting point, then work with your team to make it work best for your needs and context.
Feature branches, sometimes referred to as topical branches, are branches created for a specific purpose, like implementing a feature, or fixing a bug. Usually these branches are named after their feature, and on many teams branch names also contain the unique ID of the relevant project management task, similar to the commit message practice mentioned above.
Some benefits of feature branches include:
- Git clients let you view everything that changed in a given branch, as well as compare branches. Using these views it becomes very easy to digest all the changes done for a certain feature, almost like reading a short story
- Linking to Jira or other project management software makes this point even stronger
- With everyone on feature branches you have more control over minimizing merge conflicts rate, since fewer people are on each branch, and the team can decide when to sync their branches. In contrast, if we assume a branch-per-env model, the rate of conflicts and frustration tends to be higher
- Feature branches are convenient wrappers, allowing you to easily sync an entire feature to different branches, e.g. when others working on a long project need to sync your work into their branch so they can build upon it
Release branches are branches created in order to support all the work between creating a release cut-off and delivering it to production, including testing, bug fixing, deploying to production, and deploying hotfixes for any urgent issues discovered post-deployment.
Some benefits of release branches include:
Release cutoff workflow
- Creating a release branch is the Git way of implementing a release cut-off, a practice we've seen most teams use
- Any fixes for bugs or issues you find before releasing are added as new commits on the release branch, separate from the main branch and feature branches, allowing your team to find the right time to sync those new fixes into the other branches
- Similarly, if you discover an entire feature isn't ready to be released, you can revert that feature on the release branch and continue with the release, without having to wait for a fix. In parallel the feature owner can fix their feature and have it tested and released in the next release
- The latest release branch is the go-to branch for any hotfix, as it should represent the exact configuration currently deployed in production. Once fixed, you can sync those hotfix commits to the main branch and any other branch currently in progress
Env branches are branches meant to represent the current configuration deployed to the environment the branch is named after. This approach is used in many DevOps tools, and is in fact necessary when the content of the Git repository does not handle multiple envs at once.
At Salto we made it a priority for every repository's contents to handle multiple envs at once, because we believe this approach is most conducive to test envs being similar to each other and to production, while the env branches approach tends to enable the accumulation of differences between envs. For this main reason Salto recommends not using env branches.
Check out our complete workflows on Collaboration workflows.
Below are some excellent resources on different Git workflows that can be helpful in designing your team's workflow.
Updated 9 months ago