Add release guide for mdcms

This guide provides detailed steps for releasing a new version of mdcms, including prerequisites, setup, version bumping, tagging, and monitoring the build process.

docs/release.md

@@ -0,0 +1,92 @@
+# Releasing a new version of mdcms
+
+This guide covers publishing a new mdcms release — producing binaries, a `.deb` package, and a GitHub release with all artifacts attached.
+
+## Prerequisites
+
+- Push access to `kbenestad/mdcms` on GitHub
+- GitHub Actions enabled on the repository (it is by default on new repos)
+
+## One-time GitHub setup
+
+### Enable workflow write permissions
+
+The release workflow creates a GitHub release using the built-in `GITHUB_TOKEN`. You need to confirm it has write access:
+
+1. Go to your repository on GitHub
+2. **Settings → Actions → General**
+3. Scroll to **Workflow permissions**
+4. Select **Read and write permissions**
+5. Click **Save**
+
+That's the only setup required. No secrets, no tokens, no third-party services.
+
+## The release checklist
+
+Before tagging a release, update the version number in two places:
+
+**`mdcms.py`** — find this line near the top and bump it:
+```python
+CLI_VERSION = "0.3.1"
+```
+
+**`pyproject.toml`** — bump the matching line:
+```toml
+version = "0.3.1"
+```
+
+> **Site format version** — the markers in `app/config.yml` and `app/index.html` (`# mdcms v0.3`) are separate from the CLI version. Only update them if the site file format has a breaking change that requires users to re-download the template. Most releases do not touch these.
+
+Commit the version bump:
+```bash
+git add mdcms.py pyproject.toml
+git commit -m "Bump version to 0.3.1"
+git push origin main
+```
+
+## Tagging the release
+
+Push a version tag to trigger the workflow:
+```bash
+git tag v0.3.1
+git push origin v0.3.1
+```
+
+The tag must start with `v`. The workflow triggers immediately.
+
+> **Pre-releases** — if the tag contains a hyphen (e.g. `v0.4.0-beta.1`), the GitHub release is automatically marked as pre-release.
+
+## What the workflow does
+
+The workflow (`.github/workflows/release.yml`) runs three parallel jobs:
+
+| Runner | Output |
+|---|---|
+| `ubuntu-latest` | `mdcms-linux-amd64` (standalone binary) + `mdcms_0.3.1_amd64.deb` |
+| `macos-latest` | `mdcms-macos-arm64` (standalone binary) |
+| `windows-latest` | `mdcms-windows-amd64.exe` |
+
+Each binary is built with PyInstaller — Python is bundled inside, so end users need nothing pre-installed. The `.deb` is built with `fpm` and installs mdcms to `/usr/local/bin`.
+
+A final job collects all artifacts and creates the GitHub release with auto-generated release notes.
+
+## Monitoring the build
+
+1. Go to **Actions** on the repository
+2. Click the workflow run triggered by your tag
+3. Each platform job takes roughly 3–5 minutes
+
+If a job fails, the release is not created. Fix the issue, delete the tag, and re-push:
+```bash
+git tag -d v0.3.1
+git push origin --delete v0.3.1
+# fix the issue, then re-tag
+git tag v0.3.1
+git push origin v0.3.1
+```
+
+## The finished release
+
+Once all jobs pass, the release appears under **Releases** on the repository with:
+- Auto-generated changelog (commits since the last tag)
+- All four artifacts attached for download