mdcms/docs/release.md

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

Update version number

Before tagging a release, update the version number in two places:

mdcms.py — find this line near the top and bump it:

CLI_VERSION = "0.3.1"

pyproject.toml — bump the matching line:

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 locally

Commit the version bump:

git add mdcms.py pyproject.toml
git commit -m "Bump version to 0.3.1"
git push origin main

Commit on the web

Save each file with a version bump notice: "Bump version to 0.3.1".

Tagging the release

Locally

Push a version tag to trigger the workflow:

git tag v0.3.1
git push origin v0.3.1

On the web

1. Go to your repository → Releases (right sidebar)
2. Click Draft a new release
3. Click Choose a tag → type v0.3.0 → click Create new tag: v0.3.0 on publish
4. Leave the target branch as main
5. Click Generate release notes
6. Click Publish release

Common

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:

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