|
| 1 | +--- |
| 2 | +description: Cut a new versioned release of the book's CONTENT — bump the version, update the changelog, verify, and publish the GitHub Release with the PDF attached. |
| 3 | +--- |
| 4 | + |
| 5 | +# Release Content |
| 6 | + |
| 7 | +Publish a new **content version** of the GitHub Agentic Workflows interactive book. Versioning |
| 8 | +applies to the **prose under `content/` only** — never the site generator, PDF tooling, analytics, |
| 9 | +or any other part of the repo. |
| 10 | + |
| 11 | +**What changed:** <one-line summary of the content edits, or "read the diff since the last release"> |
| 12 | +**Version bump:** <major | minor | patch, or an explicit `x.y` — decide from the rules below if unset> |
| 13 | + |
| 14 | +## Versioning model (read first) |
| 15 | +- **Source of truth:** `content/VERSION` — a single line, e.g. `1.1`. |
| 16 | +- **History / release notes:** `content/CHANGELOG.md` — Keep-a-Changelog style; the release notes |
| 17 | + are generated from this file. |
| 18 | +- **Shared helper:** `scripts/content_version.py` (`version` / `tag` / `notes`) — the stdlib-only |
| 19 | + parser used by the site generator, the PDF builder, and the release workflow. |
| 20 | +- **Tag & Release:** each version ships as a GitHub Release tagged `content-vX.Y` with the matching |
| 21 | + single-file PDF (`gh-aw-book-vX.Y.pdf`) attached, so every past state stays reproducible. |
| 22 | +- **Automation:** `.github/workflows/release-content.yml` cuts the release automatically when |
| 23 | + `content/VERSION` changes on `main`. It is idempotent (skips if the release exists) and |
| 24 | + self-healing (re-attaches the PDF if it went missing). You normally just prepare the bump — the |
| 25 | + workflow publishes. |
| 26 | + |
| 27 | +**SemVer for prose** — pick the bump: |
| 28 | +- **MAJOR** — structural rewrite or reordering of the book. |
| 29 | +- **MINOR** — new chapters, sections, or material. |
| 30 | +- **PATCH** — corrections and clarifications only. |
| 31 | + |
| 32 | +## Steps |
| 33 | +1. **Confirm the scope.** Show what content changed since the last release: |
| 34 | + `git diff $(python scripts/content_version.py tag)..HEAD -- content/`. Summarize it for the |
| 35 | + reader. If nothing under `content/` changed, **stop** — there is nothing to release. |
| 36 | +2. **Pick the new version** `x.y` from the bump rules. The current version is |
| 37 | + `python scripts/content_version.py version`. |
| 38 | +3. **Update `content/CHANGELOG.md`.** Add a new section at the very top (keep older entries intact): |
| 39 | + ``` |
| 40 | + ## [x.y] - YYYY-MM-DD (today's date) |
| 41 | + One-line summary of this release. |
| 42 | +
|
| 43 | + ### Added / ### Changed / ### Fixed |
| 44 | + - **Bold lead:** what changed and why it matters to the reader. |
| 45 | + ``` |
| 46 | +4. **Bump `content/VERSION`** to `x.y` (single line, nothing else). |
| 47 | +5. **Verify locally — all must pass:** |
| 48 | + - `python scripts/content_version.py version` → `x.y`; `python scripts/content_version.py notes x.y` |
| 49 | + prints your new notes. |
| 50 | + - `python site/generate.py` → clean build; the header version pill and `site/versions.html` show |
| 51 | + `vx.y`. |
| 52 | + - `python scripts/build_pdf.py` → the PDF running footer reads `vx.y`. |
| 53 | +6. **Commit** the bump plus the regenerated site output: `content/VERSION`, `content/CHANGELOG.md`, |
| 54 | + and the changed `site/**` files. Message: `Release content vx.y`. Include the trailer |
| 55 | + `Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>`. |
| 56 | +7. **Publish:** |
| 57 | + - **Preferred — merge to `main`.** Open a PR and merge it. The deploy workflow republishes the |
| 58 | + site (now showing `vx.y`) and `release-content.yml` builds the versioned PDF, pulls the notes |
| 59 | + from the changelog, and creates `content-vx.y` as Latest. Re-runs are safe (idempotent). |
| 60 | + - **Manual fallback** (only if you must publish without merging). Write the notes to a file |
| 61 | + **from Python** (capturing `python` stdout into a PowerShell variable mangles em-dashes on |
| 62 | + Windows), then: |
| 63 | + ``` |
| 64 | + python scripts/content_version.py notes x.y # write output to notes.md |
| 65 | + gh release create content-vx.y \ |
| 66 | + "gh-aw-book-vx.y.pdf#GitHub Agentic Workflows — vx.y (PDF)" \ |
| 67 | + --title "Content vx.y" --notes-file notes.md --target <content-commit-sha> |
| 68 | + ``` |
| 69 | +8. **Confirm.** `gh release list` shows `content-vx.y` as **Latest** with the PDF asset attached, |
| 70 | + and the online **Version history** page (`versions.html`) lists it. |
| 71 | +
|
| 72 | +**Guardrails:** never bump the version for non-content changes; never attach a PDF that predates the |
| 73 | +content it claims to represent (that's why the first release, `content-v1.0`, ships notes-only — |
| 74 | +the PDF feature postdated it). |
0 commit comments