Git workflow and versioning
Contract
| Field |
Bound contract |
| Trigger |
User asks for release, version bump, changelog, or branch workflow beyond a single commit. |
| Authority |
Human-gated: previews the exact target and consequence before any push, protected-branch action, or force-push, with explicit consent required for protected branches and force-pushes; otherwise reversible local: writes only local commits, tags, and changelog edits; rollback is version control. No remote mutation without the gate. |
| Side effect |
Git commits, tags, and changelog edits; protected branches and force-pushes only with explicit consent. |
| Done |
History expresses logical change-sets, tags and changelog match shipped contract changes, and no unauthorized protected-branch action occurred. |
Inputs
Required: the change-set to release or version (working-tree state, staged changes, or committed history since the last tag); the target version bump type or an explicit version string; the branch to operate on.
Optional: changelog path, remote name, tag message, prerelease suffix.
Procedure
- Confirm the request names a release, version bump, changelog update, or branch workflow beyond a single commit. If it is a single commit, stop and defer to the caller. Done when: the request names a release/version/changelog/branch-workflow beyond one commit, or the run deferred a single-commit request.
- Inspect the working tree and recent history with
git status, git log since the last tag, and the current branch. Identify the logical change-sets to express. Done when: working tree, history since last tag, and current branch inspected and change-sets identified.
- Group changes into atomic commits so each commit is one logical change-set. Stage and commit each group with a message that states the change, not the diff. Done when: changes grouped into atomic commits, each one logical change-set with a change-stating message.
- Derive the version bump from the change-sets (major for breaking contract changes, minor for additive, patch for fixes), or use the explicit version the user supplied. Done when: the version bump is derived from change-sets or the user-supplied version is adopted.
- Update the changelog so each new entry matches a shipped contract change; date and version the new section. Done when: the changelog''s new entries each match a shipped contract change, dated and versioned.
- Preview the exact commits, tag, and changelog diff to the user before any tag, push, or protected-branch action. Done when: the commits, tag, and changelog diff are previewed to the user before any tag, push, or protected-branch action.
- Create the version tag only after explicit human confirmation. Use an annotated tag carrying the version message. Done when: an annotated version tag is created only after explicit human confirmation.
- For any push, protected-branch target, or force-push, state the target and consequence and require explicit consent before executing. Never force-push or push to a protected branch without it. Done when: every push, protected-branch target, or force-push states target and consequence and has explicit consent before executing.
- After mutation, verify
git log, git tag, and the changelog reflect the intended state and confirm no unauthorized protected-branch action occurred. Done when: git log, git tag, and the changelog reflect the intended state with no unauthorized protected-branch action.
Failure and recovery
- Ambiguous change-set grouping: stop and ask the user to confirm the grouping before committing.
- Version bump conflict (user-supplied version disagrees with the derived bump): use the user-supplied version; record the disagreement in the changelog only if asked.
- Protected-branch or force-push requested without explicit consent: do not execute; report the blocked target and the consent required.
- Tag or changelog section already exists for the target version: stop and report the collision; do not overwrite without explicit consent.
- Partial result: if any step after the first commit fails, leave completed commits in place, report which steps remain, and do not push or tag until the full sequence is confirmed.
- Non-converged: report the exact blocked step, the current history state, and the remaining actions. Never claim the done predicate holds while commits, tags, and changelog are inconsistent.
Output
A history of atomic commits, an annotated version tag, and a changelog section matching the shipped contract changes, plus a report listing the commits, the tag, the changelog diff, and confirmation that no unauthorized protected-branch action occurred; or a blocked or non-converged result naming the failing step.
1---2name: git-workflow-and-versioning3description: Use when the user asks for release, version bump, changelog, or branch workflow beyond a single commit. Don't use for single commits or for publishing to a package registry.4---56# Git workflow and versioning78## Contract910| Field | Bound contract |11|---|---|12| Trigger | User asks for release, version bump, changelog, or branch workflow beyond a single commit. |13| Authority | Human-gated: previews the exact target and consequence before any push, protected-branch action, or force-push, with explicit consent required for protected branches and force-pushes; otherwise reversible local: writes only local commits, tags, and changelog edits; rollback is version control. No remote mutation without the gate. |14| Side effect | Git commits, tags, and changelog edits; protected branches and force-pushes only with explicit consent. |15| Done | History expresses logical change-sets, tags and changelog match shipped contract changes, and no unauthorized protected-branch action occurred. |1617## Inputs1819Required: the change-set to release or version (working-tree state, staged changes, or committed history since the last tag); the target version bump type or an explicit version string; the branch to operate on.2021Optional: changelog path, remote name, tag message, prerelease suffix.2223## Procedure24251. Confirm the request names a release, version bump, changelog update, or branch workflow beyond a single commit. If it is a single commit, stop and defer to the caller. Done when: the request names a release/version/changelog/branch-workflow beyond one commit, or the run deferred a single-commit request.262. Inspect the working tree and recent history with `git status`, `git log` since the last tag, and the current branch. Identify the logical change-sets to express. Done when: working tree, history since last tag, and current branch inspected and change-sets identified.273. Group changes into atomic commits so each commit is one logical change-set. Stage and commit each group with a message that states the change, not the diff. Done when: changes grouped into atomic commits, each one logical change-set with a change-stating message.284. Derive the version bump from the change-sets (major for breaking contract changes, minor for additive, patch for fixes), or use the explicit version the user supplied. Done when: the version bump is derived from change-sets or the user-supplied version is adopted.295. Update the changelog so each new entry matches a shipped contract change; date and version the new section. Done when: the changelog''s new entries each match a shipped contract change, dated and versioned.306. Preview the exact commits, tag, and changelog diff to the user before any tag, push, or protected-branch action. Done when: the commits, tag, and changelog diff are previewed to the user before any tag, push, or protected-branch action.317. Create the version tag only after explicit human confirmation. Use an annotated tag carrying the version message. Done when: an annotated version tag is created only after explicit human confirmation.328. For any push, protected-branch target, or force-push, state the target and consequence and require explicit consent before executing. Never force-push or push to a protected branch without it. Done when: every push, protected-branch target, or force-push states target and consequence and has explicit consent before executing.339. After mutation, verify `git log`, `git tag`, and the changelog reflect the intended state and confirm no unauthorized protected-branch action occurred. Done when: `git log`, `git tag`, and the changelog reflect the intended state with no unauthorized protected-branch action.3435## Failure and recovery36- Ambiguous change-set grouping: stop and ask the user to confirm the grouping before committing.37- Version bump conflict (user-supplied version disagrees with the derived bump): use the user-supplied version; record the disagreement in the changelog only if asked.38- Protected-branch or force-push requested without explicit consent: do not execute; report the blocked target and the consent required.39- Tag or changelog section already exists for the target version: stop and report the collision; do not overwrite without explicit consent.40- Partial result: if any step after the first commit fails, leave completed commits in place, report which steps remain, and do not push or tag until the full sequence is confirmed.41- Non-converged: report the exact blocked step, the current history state, and the remaining actions. Never claim the done predicate holds while commits, tags, and changelog are inconsistent.4243## Output44A history of atomic commits, an annotated version tag, and a changelog section matching the shipped contract changes, plus a report listing the commits, the tag, the changelog diff, and confirmation that no unauthorized protected-branch action occurred; or a blocked or non-converged result naming the failing step.
OutlineDriven