•
Git usage guidelines for team collaboration
By Alex • 3 minutes read •
Introduction
This article outlines rules ideal for projects managed by small teams consisting of 3-8 members. These guidelines draw inspiration from conventional commits. Note that this discussion does not delve into GitFlow.
Branching model
- Always branch out from an updated “main” branch.
- Branches should be short-lived (maximum of 2 days) and focus on a specific goal.
- Once the goal is achieved, initiate a Pull Request (PR) to merge it with the main branch.
- After merging, promptly delete the branch.
- Only merge to the main branch, and ensure merges are squash merges for a tidy, brief history.
Branch names
While naming might seem trivial in tiny teams, it becomes essential for larger or remote teams. Consider the following naming convention:
<type>/[<ticket_id>]_<subject>
Applications like Sourcetree use the /
to segment branch names in their interface, helping categorize branches.
Type
- feat: Introducing a new feature.
- fix: Implementing a bug fix.
- docs: Changes exclusive to documentation.
- tests: Addition or modification of tests.
- refactor: Code alterations that neither fix bugs nor introduce features.
- style: Cosmetic code changes.
- ci: Changes to your continuous integration configuration files and scripts.
- chore: Modifications to the build process or aiding tools.
- perf: Enhancements that boost performance.
Ticket ID
If the branch’s objective is intricate or linked to a specific task, mention the corresponding ticket ID, e.g., PRJ_123
.
Subject
Describe the branch’s specific purpose in 3-4 words. If there’s no ticket ID, the description’s precision becomes even more crucial.
Commit messages
Adopting a standardized commit message structure aids in automating change logs and semantic release updates using tools like semantic-release.
Format
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, with the scope being optional. Ensure no line exceeds 100 characters for better readability across platforms.
Type
Use the previously mentioned types.
Scope
The scope provides context about the commit’s area of effect. It can be any noun pointing to a code section, or * for multiple areas.
Some teams leverage scope for ticket IDs, linking commits directly to tasks. This maintains ticket IDs in the history after squash merges.
Subject
- Adopt an imperative, present tense.
- Avoid capitalizing the first letter.
- Skip the period at the end.
Don’t use generic subjects as: ‘debug’ or ‘few fixes’. Be clear and specific.
Prioritize clarity. If you use automated changelog generators, ensure commit messages cater to all stakeholders.
Body
When used, the body should be in imperative, present tense and detail the motivation behind changes.
Footer
Reserved for details on breaking changes or referencing GitHub issues. Start with “BREAKING CHANGE:” followed by an explanation.
Pull requests (or merge requests)
Henceforth referred to as PRs, these are synonymous with merge requests.
For squash merges, the commit message format typically applies to the PR title and description. I prefer using the initial commit message of a branch as the PR title.
With Github CLI:
or Gitlab CLI:
This sets the PR title and description to the last commit message in the branch.
Code reviews
PRs allow team members to review your code changes. Always target the ‘main’ branch with your PR.
For your PR:
- Title: Concise yet descriptive.
- Description: Outline the changes, their purpose, their mechanism, potential impacts, and supplement with visuals if relevant.
- Size: Keep it below 250 lines of change.
- Modularity: Break down extensive features into smaller PRs when feasible.
- Single Responsibility: Each PR should have a singular focus.
Remember: git is a collaboration tool, not a reporting or deployment tool.
References
- 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
- Sourcetree
- GitHub CLI
- GitLab CLI
- git-cliff
- semantic-release
- python-semantic-release