Release Runbook

This document describes the process for cutting a new stable release of the Fishwrap Engine (fishwrap).

Objective: To tag a clean, tested version that downstream consumers can pin to.

---

1. The Pre-Flight Check

Before you release, ensure:

• The main branch is clean.
• You have documented the changes in docs/RELEASE_NOTES.md.

Writing Release Notes

Edit docs/RELEASE_NOTES.md. Add a new section at the top:

## vX.Y.Z (Codename) - YYYY-MM-DD

Summary of the release...

### 🚀 New Features
*   ...

Do not include the Commit Hash yet. The tag itself is the source of truth.

---

2. The Release Script

We use an automated script to enforce hygiene. This script will:

1. Update fishwrap/__init__.py.
2. Wipe the venv and rebuild it from scratch (make clean-all && make setup).
3. Run the full test suite (make test).
4. Run the pipeline (make run-vanilla) to prove it builds.
5. Commit, Tag, and Push.

Command:

./scripts/release.sh <version> "<codename>"

Example:

./scripts/release.sh 1.4.0 "The Velocity Update"

If the smoke test fails, the script aborts before tagging.

---

3. Policy: Forward Compatibility

Fishwrap separates Engine (Logic) from Theme (Presentation). When introducing new data to the templates:

1. Engine First: Update printer.py to inject the new variable (e.g., time_str) into the context. This goes into main.
2. Theme Second: Update themes (e.g., layout.html) to use the variable conditionally:

3. No Greedy Releases: Do not cut a new Engine Release just to support a minor UI tweak in a downstream consumer. Let the consumer update their theme first (it will be invisible/safe). When the next Engine Release eventually ships, the feature will light up automatically.

---

4. Hotfixes & YOLO Mode

If you need to ship a critical fix right now without a tag:

1. YOLO Mode: Downstream projects can symlink to your local development directory to test bleeding-edge changes.
   • Warning: This deploys whatever dirty state is on your laptop. Use with caution.
2. To Return to Stable: Downstream projects should reinstall the pinned version (e.g., make install-stable VERSION=v1.4.0).