Production Git Workflow Standards

Owner: Vadim Rudakov, lefthand67@gmail.com
Version: 0.1.1
Birth: 2025-11-29
Last Modified: 2026-01-14

This handbook establishes mandatory, professional-grade conventions for Git branching and committing. Adherence to these standards is essential for achieving traceability, enabling automated MLOps gates, ensuring accurate changelogs, and streamlining architectural reviews.

The workflow is enforced through a Three-Tier Naming Structure and a strict Conventional Commits policy, culminating in an Atomic Commit merge strategy.

Intro: Three-Tier Naming Structure¶

All changes must follow this strictly enforced hierarchy for complete lifecycle context.

Tier 1: Branch Prefixing Policy - Scope & Traceability¶

Branch names MUST use the format:

<prefix>/<TICKET-ID>-<short-kebab-description>

Names must be lowercase with hyphens. This format enables automatic linking to issues and Pull Requests. Not implemented yet.

Tiers 2 & 3: Conventional Commit Policy - Intent & Justification¶

Tier 2: Commit Title Prefix - What Changed¶

The commit title MUST start with <type>: <description>. The description must be 50 characters maximum and written in the imperative mood.

BREAKING CHANGE Footer¶

The official way to signal changes that break compatibility is:

<type>(<optional scope>): <description>

BREAKING CHANGE: <description of breaking impact>

Tier 3: Architectural Tagging - Why Changed¶

For commits of type

• refactor:,

• perf:, or

• BREAKING CHANGE Footer,

the architectural intent MUST be provided as an ArchTag (Architectural Tag).

• Format: The tag MUST be the first line of the commit body: ArchTag:TAG-NAME (one tag only).

• Syntax Rules: The tag MUST NOT include the # symbol or any spaces.

• Validation: CI/CD automation tools will validate the tag’s presence and correctness.

“WIP” Commits: Interactive Rebase¶

Before opening a Pull Request (PR), all intermediate commits like WIP MUST be consolidated (squashed) into one or more atomic commits using a valid semantic type (feat:, fix:, etc.).

1. Start Interactive Rebase: Execute git rebase -i <target-branch> (e.g., git rebase -i develop).

2. Edit Commit List: Change the action for every WIP: commit from pick to squash (s) or fixup (f).

3. Finalize Message: Ensure the final, consolidated commit message is a single, valid, semantic commit title and body.

A WIP: type is useful only if its temporary nature is strictly enforced. Allowing WIP: commits to pollute the final, merged history defeats the purpose of Conventional Commits and introduces unnecessary noise and technical debt.

PR System Guardrails (Hard Gates)¶

• CI/CD Block: The CI/CD pipeline is to be configured to automatically fail a Pull Request if any commit in the branch’s history contains the prefix WIP:. This is a hard technical gate.

• Mandatory Merge Strategy: The repository is configured to enforce “Squash and Merge” for all feature branches into mainline branches. This guarantees that the final history is composed of single, clean, semantic commits.

The most effective enforcement mechanism is at the code review and merge gate.

The dev’s workflow on topic branch:

$ git switch topic-branch
$ git rebase -i main

# squash intermediate commits, fix any conflicts
# then
$ git push origin topic-branch

# and initiate a PR

Guidance: When to Use “WIP:” vs. Standard Commit Types¶

New engineers must understand the difference to avoid misusing WIP:.

Atomic Commits: The Guiding Principle¶

The goal of every feature branch’s final history is logical atomicity. An Atomic Commit is a self-contained, complete, and logically isolated unit of work.

Rules of Atomicity¶

• Rule 1: One Goal Per Commit. A commit must achieve one objective only (e.g., refactor logic, add unit tests, fix a bug).

• Rule 2: Commits Must Be Stable. Every commit in the final, merged history MUST be buildable and pass all tests. This is mandatory for advanced diagnostic tools like git bisect. Broken commits are technical debt.

• Rule 3: Cohesive Narrative. The sequence of commits in a Pull Request (PR) must tell a clear story of how the feature was developed, making it easy for reviewers to follow the logic.

The “Commit by Logic” Workflow¶

To create atomic commits, DO NOT use git add . indiscriminately.

This disciplined approach ensures that your contributions are professionally structured, easily maintainable, and maximally effective for the long-term health of our engineering systems.

Merge Strategy: Atomic Change Submission¶

All changes merged into mainline branches (main, develop, etc.) MUST be integrated as a single, atomic, logical unit. This is a fundamental engineering discipline used in scaled production environments (Google, Meta, Microsoft) to ensure reviewability, revertability, and traceability.

One Change, One Commit: The BigTech Standard¶

In professional code review systems:

• A Pull Request (PR) or Change List (CL) represents one logical modification to the system.

• Intermediate development steps (e.g., test scaffolding, incremental refactors) are development artifacts, not production history.

• Preserving them in main adds noise without operational value and dilutes accountability.

Debugging Without “git bisect” Granularity¶

Fine-grained bisect on noisy history is not the primary debugging tool in production systems. Instead, rely on:

• Structured logging (with trace IDs),

• Metrics and alerting (e.g., latency, error rates),

• Atomic revert (if a change breaks, revert the entire unit—not part of it).

If a change is too large to debug or revert safely, it violates atomicity and should have been split before submission.

(To Consider) Advanced Strategy: The Stacked Diff Exception¶

The Stacked Diff workflow is permitted as an advanced implementation of Atomic Change Submission, enabling high velocity and rapid peer review. This methodology involves breaking a large feature into a series of small, dependent, atomic CLs (Change Lists or Diffs) .

1. Scope: The entire feature remains one logical change to the system.

2. Integration Method: The default Squash and Merge is overridden. The stack is integrated using a specialized tool (e.g., Sapling, Graphite) that executes an atomic Rebase and Merge or Fast-Forward Merge for each sequential diff.

3. Strict Condition: This exception is only permitted if:

   • The work is managed through an approved Stacked Diff platform.

   • Every single commit in the stack must be independently reviewed, CI-verified, and comply with all Tier 1, 2, and 3 policies.

4. Benefit: The resulting mainline history is linear, atomic, and preserves the clean narrative of the feature’s development, thus restoring the utility of git bisect for diagnostics.

Enforcement¶