← Library

— notes

Git Practices for Production Codebases

2 min read#engineering-practices
On this page
  1. Commits
  2. 1. Write Atomic Commits
  3. 2. Use Descriptive Commit Messages
  4. Branches
  5. 1. Follow a Consistent Naming Convention
  6. 2. Rebase for a Clean History
  7. Pull Requests
  8. 1. Use Clear PR Titles
  9. 2. Write PR Descriptions
  10. 3. Keep PRs Small
  11. 4. Self-Review First

Git is the backbone of every software project. Working in FinTech systems, I’ve learned that Git isn’t just a tool – it’s a shared language and a safety net.

In FinTech and regulated environments, every change must be auditable and traceable. Clean Git practices are not just about developer productivity – they are a compliance requirement.

Commits

1. Write Atomic Commits

An atomic commit focuses on one thing – fixing a bug, adding a feature, or refactoring.

Good: feat: add endpoint for retrieving user account balances Bad: misc: fix bugs and add features

2. Use Descriptive Commit Messages

<type>(<scope>): <subject>
<BLANK LINE>
<body (optional)>

The Conventional Commits Specification formalizes this format. It pairs well with commitlint and enables automatic changelog generation.

graph LR
    A["feat(parser): add bitmap validation"]
    A --> B["<b>type</b><br/>feat"]
    A --> C["<b>scope</b><br/>parser"]
    A --> D["<b>description</b><br/>add bitmap validation"]

Branches

1. Follow a Consistent Naming Convention

<JIRA-ticket-ID>-<type>-<short-description>

Examples: JIRA-5678-fix-transaction-timeout, JIRA-1234-feature-add-batch-processing

2. Rebase for a Clean History

git checkout JIRA-5678-fix-transaction-timeout
git pull --rebase origin main

Rebasing rewrites commit hashes, so it should only be used on local or feature branches. The payoff is a linear history that reads like a narrative.

gitGraph
    commit id: "init"
    commit id: "v1.0"
    branch JIRA-5678-fix-timeout
    commit id: "add retry logic"
    commit id: "handle edge case"
    commit id: "add tests"
    checkout main
    commit id: "hotfix: logging"
    checkout JIRA-5678-fix-timeout
    merge main id: "rebase onto main" type: HIGHLIGHT
    checkout main
    merge JIRA-5678-fix-timeout id: "squash merge" type: HIGHLIGHT
    commit id: "v1.1"

Pull Requests

1. Use Clear PR Titles

[JIRA-ticket-ID] <Type>: <Short Description>

Examples:

  • [JIRA-5678] Fix: Handle transaction timeout edge cases
  • [JIRA-1234] Feature: Add bulk processing for transactions

2. Write PR Descriptions

Answer three questions: What changed? Why? Does it introduce risks?

3. Keep PRs Small

Large PRs are hard to review and prone to mistakes. A schema migration should be its own PR.

4. Self-Review First

Read your diff as if a colleague wrote it before requesting review.

graph LR
    A["Branch Created"] --> B["Commits"]
    B --> C["Self-Review"]
    C --> D["PR Opened"]
    D --> E["CI Passes"]
    E --> F["Code Review"]
    F --> G["Approved"]
    G --> H["Squash Merge"]
    H --> I["Branch Deleted"]

In highly critical FinTech systems, precision isn’t optional. Clean commits, structured branches, and clear PRs are safeguards for the stability of the systems we build.