Nezam Nezam Nezam Git Workflow

Purpose

Govern repository hygiene end-to-end: branching model, conventional commits, annotated tags, PR-required checks, branch protection, and dependency automation (Renovate / Dependabot). Single-responsibility: git + GitHub workflow contract. (Absorbs the previously-proposed nezam-github-workflows.)

Inputs

• docs/specs/VERSIONING.md for semver policy.
• DevOps pipeline from @.cursor/skills/nezam-devops-pipeline/SKILL.md.
• Team conventions and repo defaults.
• Compliance regime affecting retention and audit.

Step-by-Step Workflow

1. Branching: long-lived main (protected); short-lived feature/<spec-id>-slug, release/x.y.z, hotfix/x.y.z.
2. Conventional Commits enforced at message authoring time (manual or commit-msg hook); types: feat, fix, docs, chore, refactor, perf, test, build, ci.
3. Annotated tags vMAJOR.MINOR.PATCH only on release-worthy commits listed in changelog.
4. PR checks (required): lint, typecheck, unit, contract, e2e, security (CodeQL), onboarding readiness; surface status to GitHub.
5. Branch protection on main: required reviews (≥ 1, code-owners for sensitive paths), required status checks, linear history (no merge commits), dismiss stale approvals on push, require signed commits where supported.
6. Dependency automation: Renovate (preferred) or Dependabot — group minor + patch, separate majors, security alerts auto-PR; weekly cadence.
7. Release path:
   • Run .nezam/core/scripts/release/version-plan.sh to confirm semver intent.
   • Use /DEPLOY tag to trigger GitHub release workflow with version (MAJOR.MINOR.PATCH) and optional target/prerelease.
   • Workflow creates vMAJOR.MINOR.PATCH tag and GitHub release notes.
8. Optional automation: git-automation.yml (workflow_dispatch dispatcher rejecting branch/commit ops), semantic-release.yml (workflow_dispatch only) — coordinate to avoid double-tagging.

Validation & Metrics

• 100% PRs follow Conventional Commits (lint failure blocks merge).
• Required checks gate every merge to main.
• Tag history is linear; no force-pushes to main.
• Renovate/Dependabot PRs reviewed within 7 days; security alerts within 48h.
• Release notes auto-generated and contain the changelog section.

Output Format

• .github/workflows/ci.yml (onboarding readiness + required checks).
• .github/workflows/release.yml (preview + publish).
• .github/workflows/git-automation.yml (optional dispatcher).
• .github/workflows/semantic-release.yml (optional, semantic-release).
• release.config.cjs (when semantic-release used).
• .github/CODEOWNERS and .github/pull_request_template.md.
• renovate.json or Dependabot config under .github/.
• Branch protection settings exported (markdown checklist).

Integration Hooks

• /SAVE branch|commit|tagplan runs branching + commit hygiene.
• /DEPLOY tag triggers the release path.
• /SCAN security runs CodeQL + secret scanning.
• Pairs with @.cursor/skills/nezam-devops-pipeline/SKILL.md, @.cursor/skills/nezam-secret-management/SKILL.md, @.cursor/skills/nezam-security-hardening/SKILL.md.
• Honors [.cursor/rules/workspace-orchestration.mdc](.cursor/rules/workspace-orchestration.mdc).

Anti-Patterns

• Force-push to main (or unprotected main).
• Skipping Conventional Commits ("misc", "wip").
• Tagging without an annotated message + changelog reference.
• Dependabot PRs ignored for weeks (security debt).
• Required-check list that does not include security and onboarding readiness.
• Double-tagging via parallel automation paths.

External Reference

• Conventional Commits 1.0.0 (https://www.conventionalcommits.org/en/v1.0.0/) — current.
• Semantic Versioning 2.0.0 (https://semver.org/) — current.
• GitHub branch protection / required checks (https://docs.github.com/) — current.
• Renovate (https://docs.renovatebot.com/) — current.
• Dependabot (https://docs.github.com/code-security/dependabot) — current.
• semantic-release (https://semantic-release.gitbook.io/) — current.
• Closest skills.sh/official analog: git-workflow / github-actions.

Source: iDorgham/Nezam — distributed by TomeVault.