Production Git Workflow Standards

Owner: Vadim Rudakov, lefthand67@gmail.com Version: 0.6.0 Birth: 2025-11-29 Last Modified: 2025-12-15

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.

1. Three-Tier Naming Structure¶

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

2. Tier 1: Scope & Traceability - Branch Prefixing Policy¶

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.

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

3.1 Tier 2: What Changed - Commit Title Prefix¶

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

NOTE: Commit types inform SemVer, but do not dictate it. Final SemVer must be validated against API/behavior contracts.

BREAKING CHANGE Footer¶

The official way to signal changes that break compatibility is:

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

BREAKING CHANGE: <description of breaking impact>

💡 Key principle: A breaking change is defined by observable behavior change for consumers — not by the act of change itself.

Read more: Conventional Commits – Breaking Changes
Conventional Commits Specification, Section “Commit Message with Description and Breaking Change Footer” [Conventional Commits WG], 2019
https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-description-and-breaking-change-footer

3.2 Tier 3: Why Changed - Architectural Tagging¶

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.

Example of a full commit with ArchTag¶

refactor: simplify model loading logic

ArchTag:TECHDEBT-PAYMENT
Reduced cyclomatic complexity from 15 to 8, improving maintainability.

4. 🚨 Mandatory Procedure: Handling WIP: Commits¶

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.

The WIP: commit type is strictly for personal backup and context switching on feature branches. It MUST NOT be present in the final commit history of any main branch (e.g., main, develop).

A. The Enforcement Gate: Interactive Rebase¶

Before opening a Pull Request (PR), all $\text{WIP:}$ commits MUST be consolidated (squashed) into one or more atomic commits using a valid semantic type ($\text{feat:}$, $\text{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 $\text{WIP:}$ commit from pick to squash ($\text{s}$) or fixup ($\text{f}$).

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

B. PR System Guardrails (Hard Gates)¶

• CI/CD Block: The CI/CD pipeline is configured to automatically fail a Pull Request if any commit in the branch’s history contains the prefix $\text{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.

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

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

Key Takeaway: If the commit is stable, complete, and describes an atomic, logical change that could stand on its own in the history, use a standard type. If the code is broken, half-finished, or purely a checkpoint, use WIP:.

5. 🧠 The Guiding Principle: Atomic Commits¶

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 $\text{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.

Read more:

• “Pro Git”, Chapter 7: Git Tools - Rewriting History’ [Scott Chacon and Ben Straub] https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

5. 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.

A. The BigTech Standard: One Change, One Commit¶

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.

Key Principle: “If it can’t be reviewed, reverted, or reasoned about as a single unit, it’s not production-ready.”

B. Implementation: Enforced “Squash and Merge” (Default)¶

• Unless otherwise specified in 5.D, all PRs must be merged using “Squash and Merge”.

• The final commit message must be:

  • A valid Conventional Commit (feat:, fix:, etc.),

  • ≤50 characters in title,

  • Include a body containing:

    • Architectural rationale (with ArchTag if required),

    • BREAKING CHANGE: footer if applicable,

    • Link to ticket or design document.

Why not “Rebase and Merge”? While linear, it preserves intermediate development commits that were never reviewed as independent units. In BigTech, only the integrated state is production-grade—everything else is a draft.

C. 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.

D. 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 $\text{git bisect}$ for diagnostics.

Enforcement¶

Exception: PRs tagged with ArchTag:REFACTOR-MIGRATION may use “Rebase and Merge” only if approved by an Architect and each commit is independently CI-verified. Stacked Diffs are the preferred method for such large-scale changes.

6. Quick Reference, Enforcement, and Pitfalls¶

6.1 Quick Reference Table¶

6.2 Enforcement¶

• CI/CD Pipeline: The pipeline MUST block a merge if:

  1. A commit of type refactor:, perf:, or BREAKING CHANGE Footer is missing a valid ArchTag.

  2. Any commit in the PR history contains the prefix WIP:.

• Architectural Review Gate: PRs containing ArchTag:REFACTOR-MIGRATION or ArchTag:DEPRECATION-PLANNED MUST receive explicit approval from an Architect/Principal Engineer before merging.

6.3 Common Pitfalls¶