old.cms.fellies.org/docs/product-engineering/git-flow-governance.md

Git Flow Governance

Scope

Governance rules for branch protections, PR gates, branch naming, and merge discipline.

Branch Protection

Protected branches:

• main
• staging

Apply protections using:

• Gitea UI settings
• or automation script: .gitea/scripts/configure-branch-protection.sh

Minimum policy:

• no direct pushes
• PR merge required
• required status checks
• at least one reviewer approval

Branch Protection Verification Checklist

Use this checklist in Gitea repository settings after applying policy:

1. main protection exists and direct push is disabled.
2. staging protection exists and direct push is disabled.
3. Required checks include:
   • Governance Checks
   • Lint Typecheck Unit E2E
4. Pull request approval is required.
5. Branch must be up to date before merge (recommended in protected branches).

API automation example:

sh .gitea/scripts/configure-branch-protection.sh \
  "$GITEA_URL" \
  "$GITEA_OWNER" \
  "$GITEA_REPO" \
  "$GITEA_ADMIN_TOKEN"

Notes:

• The script applies baseline protection for main and staging.
• Final verification is still required in the Gitea UI to confirm repository-specific policies.

PR Gates

Required checks are implemented in .gitea/workflows/ci.yml:

• Governance Checks
• Lint Typecheck Unit E2E

Branch Naming and TODO Scope

Allowed branch prefixes:

• todo/
• refactor/
• code/

Validation script:

• .gitea/scripts/check-branch-name.sh

Rule:

• one primary TODO item per delivery branch

PR TODO reference enforcement:

• template: .gitea/PULL_REQUEST_TEMPLATE.md
• CI check: .gitea/scripts/check-pr-todo-reference.sh

Branch Lifecycle

1. Create short-lived branch from latest integration tip.
2. Implement one primary scope.
3. Open PR and pass required checks.
4. Merge into dev.
5. Promote dev -> staging -> main.

Commit and Tag Policy

• Conventional commits required (CONTRIBUTING.md)
• release tags: vX.Y.Z
• changelog generated from commit history