A Source Code Management Guideline You Might Need

I often notice that in some development teams, there are different understandings of how to use Git, such as branch naming, writing commit messages, and even handling code conflicts. These varied understandings ultimately lead to chaotic content in the code repository. Especially when your dev team has ~10 members, it becomes necessary to standardize the use of Git.

In my team, we use Git for code version control and Jira for task tracking, and I'd like to share some Git usage guidelines and experiences here. This process defines branch standards, commit standards, and the code review process.

---

1. Branching Strategy

1. Use the master branch as the main branch of the project; all software releases should be based on this branch.
2. The development branch contains the latest functional code of the project.
3. All feature branches should be branched off from the development branch.
4. feature branch must be rebased before merging into the development branch to ensure they have the latest code from the development branch.
5. All hotfix branches should be branched off from the master branch.
6. Once the hotfix branch has completed the fixes, merge it into the master branch first to ensure the stability of the production environment.
7. Before merging the hotfix branch into the development branch, resolve all conflicts.
8. When the code in the development branch is ready for release, a designated developer should submit a pull request and merge the code into the master branch.
9. The master and development branches do not accept any commits except through pull request merges.
10. Merge commits are only allowed through pull requests and should only exist on the master and development branches. There should be no merge commits on feature and hotfix branches; developers need to use git rebase to keep their branch history clean.
11. No requirements are imposed on personal branches, but their content should not be merged into the development branch.

Below is a branching strategy illustration.

Based on this strategy, the commit history should be very clean, and each commit's hash key can be traced in the corresponding pull request record.

2. Branch Naming

2.1 Naming Format

All branch names should follow the format below. Except for special branches (master, main, development), all other branches should include a description.

<type>/<description>

2.2 Naming Rules

Use lowercase letters (a-z), numbers (0-9), and hyphens (-). Slash (/) should only be used to separate type and description. No other characters should be used.

Correct examples:

• main
• development
• feature/attachment-upload-support
• feature/jira-1234-upload-page
• hotfix/1.2.3
• chore/document-update

Incorrect examples:

• rock&roll
• file-upload
• feature/Security_2025
• Security-2025
• hotfix/-1.2.3
• hotfix/1.2.3-
• chore//DocumentUpdate

2.3 Branch Types

The following are all the allowed category names:

• main, master: The Main branch (e.g., main, master)
• development: The Development branch (e.g., development)
• feature: For new features (e.g., feature/jira-1234-file-upload)
• hotfix: For production bug fixes (e.g., hotfix/jira-2345-file-path)
• chore: For non-code changes, like gem upgrades or doc updates (e.g., chore/upgrade-rails-to-7.x)

You can also create branches for testing, refactoring, or research using your name. It is recommended to use names recognizable by team members (e.g., louis, john).

• louis/device-register-spike
• john/admin-page-refactor

Avoid using names unfamiliar to team members:

• louee/self-research (who are you?)

2.4 Protected Branches

The master and development branches need to be protected by setting branch ruleset. The branch ruleset is a feature provided by the GitHub.

2.4.1 Master Branch

The master branch should only be used for product release.

1. Restrict deletions
2. Require linear history
3. Require a pull request before merging
   1. Dismiss stale pull request approvals when new commits are pushed
   2. Require conversation resolution before merging
4. Block force pushes

2.4.2 Development Branch

1. Restrict deletions
2. Require a pull request before merging
   1. Require conversation resolution before merging
3. Block force pushes

Following these rules will protect the master and development branches from unintended damage. All changes must be merged through pull requests.

3. Commit Message Guidelines

3.1 Format

A commit message consists of three parts: title, body, and footer. Please follow the format below.

<type>: <description>

[optional body]

<footer>

3.2 General Rules

1. The first line should not exceed 50 characters.
2. Other lines should not exceed 75 characters.
3. The body section is optional.
4. The footer section is mandatory.
5. If certain information needs to be included in code comments, do not write it in the commit message.

Indicates the type of commit, helping developers quickly locate changes in the history.

The following are the available categories:

• feat: For new features
• fix: For bug fixes
• chore: For non-code changes, like gem upgrades
• docs: For documentation updates, like README.md
• refactor: For code refactoring
• test: For unit test updates
• ci: For CI/CD workflow updates

A brief description of the commit content, helping developers understand the change history. The description should start with a lowercase letter and should not end with a period.

When the title cannot fully explain the changes in a commit, the developer should provide an explanation in the body section.

The footer should include the JIRA ticket number related to the commit. If additional references are needed to explain the commit, URLs can be added to the footer.

3.3 Examples

A simple commit should at least include a brief summary and a JIRA ticket number.

feat: update what's new
​
JIRA: CB5503-1234

If the title cannot fully describe the commit, add a description in the body.

feat: allow users to edit uploaded file name
​
Users can edit the file name after uploading it to the system. The file name should also be reflected when they download the file from our system.

JIRA: CB5503-1234

Referencing multiple JIRA tickets.

fix: resolve file upload issue
​
Fixed a bug that prevented users from uploading files. The issue was caused by an incorrect S3 path.
​
JIRA: CB5503-1234, CB5503-4567

Referencing additional external resources.

fix: rename variables
​
Rename variables by following the team naming convention rules.
​
JIRA: CB5503-1234
Refs: https://url_to_naming_convention_rules.com

fix: rename variables
​
Rename variables by following the team naming convention rules.
​
JIRA: CB5503-1234
Refs:
- https://url_to_naming_convention_rules_1.com
- https://url_to_naming_convention_rules_2.com

Referencing other commits in the project.

fix: additional fixes for the file upload
​
JIRA: CB5503-1234, CB5503-4567
Refs: baeb5e499e, 9ab19918ad 

4. Code Review Workflow

All code submitted to the master and development branches should undergo code review. Code reviews are conducted in two forms: personal review and team inspection. GitHub's pull request feature is a tool for team inspection.

4.1 Definitions

1. Findings: Issues or improvements identified during code review, such as coding errors, security vulnerabilities, and performance bottlenecks. Documenting findings provides actionable feedback to ensure code quality before merging.

4.2 General Rules

1. Reviewers should provide all findings as review comments, rather than a single comment.
2. Reviewers' feedback should be clear and unambiguous.
3. Each finding should describe a specific issue.
4. Authors should respond to each finding seriously, ensuring all findings are resolved before merging the code.

4.3 Workflow

1. Complete the development work.

2. The developer needs to create a pull request and fill in the required information.

   1. Select the base and head branches.
   2. Fill in the JIRA ticket number and a brief description. <ticket-number>: <description>
   3. Use Markdown to write a more detailed description to help the reviewer quickly understand the pull request. Add additional comments if necessary.
   4. Select the code reviewers.

3. Reviewers should review the code and provide feedback upon receiving the review request.

   1. There are three types of findings:
      1. Suggestion: These findings should start with Suggestion:.
      2. Defect: These findings should start with Defect:.
      3. Any other findings do not have a specific format requirement.

4. The code author should respond to the findings.

   1. Each finding must be addressed in one of three ways:
      1. Fixed: Indicates the finding has been fixed. Respond with Fixed., followed by any additional comments.
      2. Declined: Indicates the finding does not require changes. Respond with Declined., followed by any additional comments.
      3. Deferred: Indicates agreement with the finding but cannot be fixed at the current time. The author must create a corresponding JIRA ticket and respond with Deferred: <ticket-id>, followed by an explanation of the deferral.

5. If the code has corresponding changes, notify the reviewer to repeat step 3.

6. Check if the current branch contains all changes from the base branch. If not, rebase is required.

7. Click the "Merge pull request" button to merge the code.

4.4 Example

NOTE: Since I only have one GitHub account, I acted as both the author and the reviewer of the pull request. In a real-world project, these roles are typically handled by two different people to ensure proper code review and maintain code quality.

Create a pull request. The red dots indicate the step 2 in the 4.3 Workflow.

The code review is sent out by review comment, not the comment. Each finding are start with a type.

Fix a defect.

Decline a suggestion

4.5 GitHub Pull Request Template

It is a good practice to use a pull request template. Create a file .github/pull_request_template.md in your project root directory.

# Summary

<!-- Describe the changes you made -->

# Checklist

- [ ] I have tested my changes locally.
- [ ] I have updated the documentation (if applicable).
- [ ] ...

Project members will automatically see the template in the pull request body.

Get more information about the pull request from GitHub official document - Creating a pull request template for your repository.

---

Setting up a source code management plan for your team is a good practice, as it can save a lot of time spent discussing branch and commit naming conventions. A clear standard work process can make your code reviews faster and more efficient. Developers no longer need to waste time trying to interpret ambiguous review comments.

Of course, this guideline is not absolutely correct or suitable for every team. For example, the branch strategy included here is a general-purpose approach I’ve developed based on years of experience, it doesn’t mean it’s the only right way. You are absolutely encouraged to adapt it to your team’s specific needs or adopt other, better strategies.

In writing this guideline, I referred to Conventional Commits and Conventional Branch. If you want to quickly apply some simple strategies to your project, you can also directly refer to the standards used in those two projects.

Feel free to discuss and share your best practices in the comments!