Release & Hot-Fix Workflow

This document explains how to cut a new feature release or a hot-fix in the ostruct project. It is intentionally lightweight.

Branching model (TL;DR)

• ``main`` – the only long-lived branch. All daily work happens here.

• Tags – every published version (v1.1.0, v1.1.1 …) is an annotated git tag on main.

• Hot-fix branch – created only if you must fix the current release without pulling in unreleased work that is already on main. Delete it right after the tag is pushed.

Workflow for a new feature release

Before writing code

1. Make sure you are on main and up-to-date:

   git switch main
   git pull --ff-only origin main
   

2. Create a short feature branch (optional but recommended):

   git switch -c feature/<short-name>
   

3. Implement the feature, update tests, update ``CHANGELOG.md`` incrementally.

4. Test locally with CI simulation:

   ./scripts/test-like-ci.sh
   

5. Open a PR (even if you merge it yourself) – CI must be green.

Tagging the release

1. Merge your PR into main.

2. Verify CHANGELOG.md and docs are ready.

3. Tag and push:

   git switch main
   git pull --ff-only
   git tag -a v1.1.0 -m "v1.1.0: short summary of highlights"
   git push origin main v1.1.0
   

That’s it—CI publishes to PyPI, updates Homebrew, builds Read the Docs, etc.

Workflow for a hot-fix release

Scenario A – fix is already on main and safe to release

1. Ensure CHANGELOG.md has a Hot-fix entry.

2. Tag and push directly from main:

   git switch main && git pull --ff-only
   git tag -a v1.1.1 -m "v1.1.1: urgent bug-fix …"
   git push origin main v1.1.1
   

Scenario B – fix must not include unreleased work on main

1. Create a throw-away branch from the last tag:

   git switch -c hotfix/v1.1.1 v1.1.0
   

2. Cherry-pick or implement just the necessary commits.

3. Update CHANGELOG.md in that branch.

4. Tag & push:

   git tag -a v1.1.1 -m "v1.1.1: security hot-fix …"
   git push origin hotfix/v1.1.1 v1.1.1
   

5. After CI turns green, delete the branch:

   git push origin --delete hotfix/v1.1.1
   git branch -D hotfix/v1.1.1
   

Do’s and Don’ts

Do ✓

• Keep main in a releasable state; let CI protect you.

• Use annotated tags (-a) for every version – they drive dynamic versioning.

• Update the CHANGELOG steadily while you code.

• Delete merged or obsolete branches immediately.

• Test the published package with pipx install ostruct-cli==<version>.

Don’t ✗

• ✗ Don’t create long-lived release/x.y branches – history gets messy.

• ✗ Don’t edit the version in pyproject.toml – tags control the version.

• ✗ Don’t force-push to shared branches or tags.

Where to find this guide

• Docs: docs/source/contribute/release_workflow.rst (rendered on Read the Docs).

• Quick link in repo root: The first section of RELEASE_CHECKLIST.md links back here for easy discovery.