# 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