release

# Photofield Release Process Follow these steps to create a new Photofield release. ## 1. Prerequisites Before starting, verify all of these: ```bash # Must be on main git branch --show-current | grep -q '^main$' ``` ```bash # Working directory must be clean git diff-index --quiet HEAD -- || { echo "NOT CLEAN"; exit 1; } ``` ```bash # CI must be passing on current HEAD curl -s "https://api.github.com/repos/SmilyOrg/photofield/commits/$(git rev-parse HEAD)/status" | grep -q '"state":"success"' && echo "CI PASSING" || echo "CI NOT PASSING" ``` If any check fails, stop and report the issue to the user. Do not proceed. ## 2. Check for Unreleased Changes ```bash ls -la .changes/unreleased/ ``` If the directory contains only `.gitkeep`, there are no unreleased entries. Tell the user: *"No unreleased changelog entries found. Nothing to release."* List each entry for the user (read the YAML files): ```bash for f in .changes/unreleased/*.yaml; do [ -e "$f" ] || continue kind=$(grep '^kind:' "$f" | sed 's/kind: //') body=$(grep '^body:' "$f" | sed 's/body: //') echo "- [$kind] $body" done ``` ## 3. Determine Next Version Changie's auto-bump rules (from `.changie.yaml`): | Kind | Bump type | Semantic meaning (at 0.x) | |--------------------|-----------|---------------------------| | `Breaking Changes` | minor | `0.X.0 → 0.(X+1).0` | | `Added` | minor | `0.X.0 → 0.(X+1).0` | | `Removed` | minor | `0.X.0 → 0.(X+1).0` | | `Deprecated` | minor | `0.X.0 → 0.(X+1).0` | | `Fixed` | patch | `0.X.Y → 0.X.(Y+1)` | | `Security` | patch | `0.X.Y → 0.X.(Y+1)` | **Rule:** If *any* entry is a minor-bump kind, bump **minor**. Otherwise bump **patch**. ```bash CURRENT=$(changie latest | sed 's/^v//') MAJOR=$(echo "$CURRENT" | cut -d. -f1) MINOR=$(echo "$CURRENT" | cut -d. -f2) PATCH=$(echo "$CURRENT" | cut -d. -f3) ``` Check if any entry is a minor-bump kind: ```bash # Sets BUMP to "MINOR" if any entry is a minor-bump kind, otherwise "PATCH" BUMP=$(grep -l -E '^kind: (Breaking Changes|Added|Removed|Deprecated)' .changes/unreleased/*.yaml 2>/dev/null | grep -qv '^$' && echo "MINOR" || echo "PATCH") ``` ```bash if [ "$BUMP" = "MINOR" ]; then NEXT="v${MAJOR}.$((MINOR+1)).0" else NEXT="v${MAJOR}.${MINOR}.$((PATCH+1))" fi ``` ## 4. Ask the User Show the user: - Current version (`$CURRENT`) - Unreleased entries (list each kind + body) - Suggested next version (`$NEXT`) - Suggested release title (see §5) **Do not proceed until the user confirms.** ## 5. Set Release Title Replace the default date-based title with a descriptive one: | Release type | Title convention | |---|---| | Patch | `"Security patches"`, `"Bug fixes and dependency updates"`, `"Stability improvements"` | | Minor | Short phrase summarizing the main feature(s) | Example edit for `.changes/$NEXT.md`: ```yaml oldText: "## [$NEXT] - 2026-06-16" newText: "## [$NEXT] - Security patches" ``` ## 6. Batch and Merge ```bash # Merge unreleased fragments into version file changie batch "$NEXT" # Review the generated file cat .changes/$NEXT.md # Set a descriptive title (see §5) # Use edit to replace the title line in .changes/$NEXT.md # Merge into CHANGELOG.md changie merge ``` ## 7. Commit and Tag ⚠️ The `task release` target has `changie batch` and `changie merge` **commented out** — it expects the agent to run them first. Do **not** run `task release` (it will fail on a dirty tree). ```bash git add CHANGELOG.md .changes/$NEXT.md git commit -m "Release $NEXT" git tag -a "$NEXT" -m "Release $NEXT" ``` ## 8. Review ```bash git show HEAD task release:changelog ``` Verify: - Changelog looks correct and well-formatted - Tag message matches - Commit only contains expected files (CHANGELOG.md + .changes/$NEXT.md) Show the review output to the user. ## 9. Push (Only With Approval) **Always ask before pushing.** Show: ``` Release ready to push: - Commit: <hash> — Release $NEXT - Tag: $NEXT - Changelog: <summary> Push? (yes/no) ``` Once confirmed: ```bash git push git push --tags ``` Then report: > Release pushed ✓ > - Commit: `<hash>` → `main` > - Tag: `$NEXT` > - CI running: https://github.com/SmilyOrg/photofield/actions ## 10. Undo Procedures ### Before push ```bash git tag -d "$NEXT" git reset --hard HEAD~1 ``` ### After push (Only With Explicit Approval) ```bash git tag -d "$NEXT" git push origin :refs/tags/$NEXT git reset --hard HEAD~1 git push --force-with-lease origin main ``` Then fix the issue and restart from §6. ## Quick Reference | Command | Purpose | |---------|---------| | `changie latest` | Get current latest version | | `ls .changes/unreleased/` | List unreleased entries | | `changie batch <v>` | Batch entries into version file | | `changie merge` | Merge into CHANGELOG.md | | `changie new -k <kind> -b <body>` | Create a changelog entry inline | | `git add CHANGELOG.md .changes/<v>.md` | Stage for commit | | `git commit -m "Release <v>"` | Create release commit | | `git tag -a <v> -m "Release <v>"` | Create annotated tag | | `git push && git push --tags` | Push release | | `task release:changelog` | Preview changelog | | `task release:undo` | Undo last release (only if not pushed) | ## Common Pitfalls 1. **Dirty working directory** — `task release` will fail. Stage and commit changie outputs first. 2. **Wrong version bump** — If you have *any* minor-bump entries but only bump patch, the version is wrong. Always check all entry kinds. 3. **Missing `.changes/<v>.md`** — This file must be committed alongside `CHANGELOG.md`. 4. **Changie `-e` flag** — `changie new -e` opens an editor. Use `-b` to set body inline: `changie new -k Fixed -b "Fix description"`. 5. **`git push` bypasses branch rules** — The repo requires PRs for non-release commits. The release commit is exempted (remote logs "Bypassed rule violations for refs/heads/main"). This is expected.