Added release doc

zsimic · Jun 24, 2026 · Jun 23, 2026 · Jun 24, 2026 · Jun 24, 2026 · Jun 24, 2026
commit 05c2c53ce8d7d0150b179174ff42333e2dad9248
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,16 @@
+---
+type: Changelog
+title: Changelog
+description: High-level release highlights for portable-python, newest first.
+tags: [changelog, releases]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# Changelog
+
+Release highlights, newest first — a rough idea of the main changes per release, not an exhaustive
+log. Maintained per the [release process](/release.md).
+
+## Unreleased
+
+_Highlights for the next release go here — see the [release process](/release.md)._
diff --git a/docs/index.md b/docs/index.md
@@ -18,6 +18,8 @@ Start with the [Overview](/overview.md), then drill into the area you need.
 * [External Modules](/modules/index.md) - The C libraries compiled and statically linked into CPython.
 * [Configuration](/configuration/index.md) - The `portable-python.yml` file, its sections and overrides.
 * [Guides](/guides/index.md) - Playbooks for common tasks: building, extending, local development.
+* [Release process](/release.md) - How to cut a release: changelog highlights, then a version tag.
+* [Changelog](/changelog.md) - High-level release highlights, newest first.
 
 ## Conventions
 

diff --git a/docs/log.md b/docs/log.md
@@ -2,6 +2,7 @@
 
 ## 2026-06-23
 
+* **Creation**: Added the [release process](/release.md) playbook and the [changelog](/changelog.md).
 * **Creation**: Added the [bump component versions](/guides/bump-components.md) guide.
 * **Update**: Pulled two verified facts in from the project wiki — the relativization tools (`patchelf` / `install_name_tool`) and `--prefix` / `--enable-shared` support ([PythonInspector](/architecture/python-inspector.md)), and the `#sha256=` download-checksum URL fragment ([configuration](/configuration/portable-python-yml.md)). Skipped the wiki's `sources:` download-url design — it's an unimplemented draft.
 * **Update**: Trimmed the CLI pages — dropped the per-command option tables (which mirror `--help`) for purpose + non-obvious gotchas + examples, pointing at `--help` for the full flag list.

diff --git a/docs/release.md b/docs/release.md
@@ -0,0 +1,52 @@
+---
+type: Playbook
+title: Release Process
+description: >-
+  How to cut a release for this repo — refresh the changelog highlights, then tag a new
+  version from a clean main.
+tags: [playbook, release, versioning, changelog]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# Release Process
+
+Releasing is opinionated and per-repo; this is portable-python's convention. A release is cut by
+pushing a version tag from `main` — that's what triggers the build + PyPI publish (see
+[CI/CD](/guides/ci-cd.md)).
+
+## 1. Refresh the changelog
+
+Review what changed since the last release:
+
+```bash
+git diff <last-tag>..main        # e.g. git diff v2.0.0..main
+```
+
+Summarize the **highlights** in [`changelog.md`](/changelog.md) — short and high-level. It should
+give a reader a rough idea of the main changes since the last release, not a blow-by-blow; skip the
+details.
+
+- If the changelog is **already up to date** with `main`, go to step 2.
+- If it's **not**, update it first — recommend landing that as its own PR before releasing.
+
+## 2. Tag the release
+
+Only once `main` is ready: the changelog is up to date, and you're on a **clean checkout of
+`main`**.
+
+Choose the bump — **ask the user; default to patch** — following semver from the last tag:
+
+| Bump | When | Example |
+|------|------|---------|
+| patch | fixes, component bumps, docs | `v2.0.0 → v2.0.1` |
+| minor | backward-compatible features | `v2.0.0 → v2.1.0` |
+| major | breaking changes | `v2.0.0 → v3.0.0` |
+
+Then **confirm the exact version with the user, and show these two commands before running them:**
+
+```bash
+git tag v2.0.1
+git push origin v2.0.1
+```
+
+The tag push is what kicks off the release — there's nothing else to run.