release-flow

name	release-flow
description	Execute this repository's release process with two commits: code first, then hash-based changelog update.

Release Flow (Hash-Based Changelog)

Goal

Follow the repository policy for releases:

1. Commit code changes first.
2. Update CHANGELOG.md with the code commit hash.
3. Commit changelog update as a separate commit.

Rules

• Use Conventional Commits for all commits.
• Include scope when possible.
• Changelog is hash-based, not version-based.
• Changelog hash must exactly match the code commit hash.

Inputs

• Pending working-tree changes.
• Intended change summary.
• Optional preferred commit scope (for example: zsh, config, tools, release).

Workflow

1) Classify changes

Split pending files into:

• Code/runtime changes
• Docs-only changes
• Changelog changes

Decision:

• If code exists: run full two-commit flow.
• If docs-only: create docs commit; only update changelog if explicitly requested or policy requires.

2) Validate before code commit

Run targeted checks for modified areas (syntax/lint/smoke as applicable).

Minimum for this repo:

zsh -n <changed-file>.zsh

For broad script changes:

rg --files -g '*.zsh' | while read -r f; do zsh -n "$f" || echo "SYNTAX_ERROR $f"; done

3) Create code commit

• Stage only code/runtime files.
• Commit with Conventional Commit + scope when possible.

Examples:

• fix(zsh): resolve proto bootstrap ordering
• feat(tools): migrate neovim provisioning to proto

4) Capture code commit hash

Record HEAD hash from the code commit. This hash is required for changelog entry header.

5) Update changelog with hash entry

In CHANGELOG.md, add:

## <commit-hash> - <YYYY-MM-DD>

### Commit
- <exact conventional commit title>

### Added
- None.

### Changed
- None.

### Fixed
- None.

### Removed
- None.

### Security
- None.

Guidance:

• Fill sections with concise bullets where applicable.
• Use None. for empty sections.
• Do not add versioned release headers.

6) Create changelog commit

• Stage only CHANGELOG.md (unless explicitly instructed otherwise).
• Commit with Conventional Commit + scope.

Examples:

• docs(changelog): record fix(zsh) release 21bfbbb
• chore(release): update changelog for 21bfbbb

7) Verify completion

• Last two commits are ordered correctly:
  1. code commit
  2. changelog commit
• Changelog hash equals code commit hash.
• Working tree is clean (or only intentionally excluded files remain).

Edge Cases

Mixed code + docs

• Keep first commit code-only when possible.
• Keep changelog in second commit.
• Put unrelated docs in a third commit if needed.

Hash mismatch

• Fix changelog entry to the exact code hash.
• Recommit changelog entry.

Example prompts

• "Release current changes using repo flow."
• "Commit code first, then add hash changelog entry and commit it."
• "Perform release with scope fix(zsh), then docs(changelog)."