Git Flow¶

Purpose and scope¶

This document defines the branching, commit, and release strategies for the mcp-hangar project. It covers routine development, bug fixes, feature implementation, and administrative flows. Adherence ensures a clean, searchable history and reliable automation.

This document does not cover Architectural Decision Record (ADR) governance. ADR governance rules reside in docs/adr/AGENTS.md. General repository conventions, such as language requirements and source layout, are in the root AGENTS.md. External contributors should also consult CONTRIBUTING.md for environment setup.

Rules defined here are enforced by CI via required status checks (pr-title.yml, branch-name.yml, changelog-check.yml, pr-body.yml, pr-validation.yml, security.yml). Enforcement details are listed in Section 12.

Decision log¶

The following table tracks the evolution of git and workflow standards.

Branch naming and merge strategy¶

The project uses a squash-merge strategy for all pull requests. Rebase-merge and merge-commit are disabled at the repository level. This preserves a linear history where every commit on main corresponds to exactly one PR whose title was validated by pr-title.yml. Branch names must follow a structured prefix pattern to support automation.

Standard prefixes:

• feat/- (new features)
• fix/- (bug fixes)
• perf/ (performance optimizations)
• refactor/ (code restructuring without behavior change)
• docs/ (documentation changes)
• test/ (test suite additions or modifications)
• build/ (build system or dependency changes)
• ci/ (continuous integration configuration)
• chore/ (routine maintenance)
• hotfix/ (emergency fixes)

Tool-specific prefixes:

• dependabot/* (automated dependency updates)
• copilot/- (AI assisted changes)
• release-please--* (automated release preparation)

Including issue numbers in branch names is optional but encouraged for complex fixes.

Conventional Commits scope reference¶

Scopes provide context to the nature of a change. They are used in commit messages: <type>(<scope>): <subject>.

Rejected scopes:

• auth (collapse into security)
• events (collapse into core)
• cqrs (collapse into core)

Deferred:

• proto (revisit when protobuf change frequency justifies)

Flow 1: Bug fix¶

Routine bug fixes target the main branch. Critical production issues follow the hotfix sub-flow.

flowchart TD
    A[Identify bug] --> B{Urgency?}
    B -- Routine --> C[Branch from main]
    C --> D[Write failing test]
    D --> E[Implement fix]
    E --> F[PR to main]
    F --> G[Squash merge]
    B -- Critical --> H[Branch from last tag]
    H --> I[Implement hotfix]
    I --> J[Manual tag vX.Y.Z-hotfix.N]
    J --> K[Cherry-pick to main]
     K --> L[See HOTFIX_RUNBOOK.md]

Hotfix branches must branch from the specific version tag where the bug exists. Manual tagging is required before cherry-picking the fix back to the main branch. Detailed operational steps are located in HOTFIX_RUNBOOK.md.

Flow 2: Feature¶

Features are developed in isolation and merged once they meet quality gates.

flowchart TD
    A[Start feature] --> B[Create feat/ branch]
    B --> C[Iterative development]
    C --> D[Run tests and lint]
    D --> E[Draft PR]
    E --> F[Code review]
    F --> G[Squash merge to main]

400 LOC is a rule of thumb / decomposition trigger, not a hard rule. Some 600-LOC features are obvious; some 200-LOC features beg to be split. Use judgment.

Feature flags are an option for multi-PR features. They are not the default. Flag infrastructure carries cost and should be used only when continuous integration requires it.

Flow 3: Epic and ADR¶

Large architectural changes require a formal Decision Record before implementation.

flowchart TD
    A[Identify major change] --> B[Draft ADR in issue comment]
    B --> C[Create PR with ADR file]
    C --> D[RFC phase]
    D --> E[Merge ADR as Accepted]
    E --> F[Implementation PRs]

Pre-community Phase A fallback¶

Until the project has at least 5 active external contributors, Phase A may be conducted as a draft PR with Status: Proposed and label rfc, held open for a 5-14 day soak. GH Discussion is not required. If external comment arrives, incorporate. If not, proceed to merge after soak. Revisit this fallback when sustained Discussion traffic exists.

ADRs must be merged before implementation begins. Once a status is set to **Status:** Accepted (per ADR-006 line 3), the ADR is immutable. Changes require a new ADR that supersedes the old one with bidirectional references. Agents may draft ADRs in issue comments but never author the PR.

Decision Tree: Issue vs Discussion vs PR¶

Deprecation policy¶

The project is at v1.1.0 and follows standard SemVer deprecation rules:

• Deprecations must be marked in at least one minor release.
• Removal occurs earliest in the next major release.
• ADR-008 will formalize additional deprecation workflow details.

Pre-release flow¶

Pre-releases allow for testing artifacts in a controlled environment. This is an operational workflow driven by tags.

Tagging vX.Y.Z-rc.N triggers .github/workflows/release.yml to publish to TestPyPI. The project uses alpha, beta, and rc suffixes for lifecycle management. Promoting a release to production is done by tagging vX.Y.Z (no -rc suffix). This triggers the same workflow to publish the final artifact to PyPI.

Reference .github/workflows/release.yml for the specific logic of tag-driven publishing.

Release cadence and process¶

Releases are currently ad-hoc based on feature readiness and security needs. This follows the decision made in section 2, row 6.

release-please runs on every push to main and maintains a long-running Release PR (release-please--branches--main) summarizing the next release. Merging that PR creates the version tag, which release.yml consumes to publish to PyPI and GHCR. There is no scheduled release cron -- the Release PR sits open until a maintainer decides "enough has accumulated."

Hotfix process¶

Hotfixes are emergency releases to address critical production regressions or CVEs. They bypass the standard feature flow to provide rapid resolution.

A hotfix branch is cut directly from the target version tag. After verification, the fix is tagged and then cherry-picked into the main branch. Detailed manual steps are in HOTFIX_RUNBOOK.md.

Automation surface¶

Active today¶

• enterprise-import-boundary (enforced in security.yml)
• pr-validation.yml (lint and basic unit tests)
• ci-core.yml (domain and application tests)
• ci-helm.yml (chart linting)
• ci-operator.yml (operator SDK tests)
• ci-docs.yml (MkDocs build validation)
• release.yml (TestPyPI and PyPI publishing)
• release-please.yml (automated version bump and Release PR)

• security.yml (static analysis and boundary checks)

• stale bot (stale.yml)

• Dependabot auto-merge (dependabot-automerge.yml)

Reviewer-only (not auto-enforced)¶

• Deprecation policy: violation caught by reviewer, not by CI.