# Release workflow

This document covers the automatic creation of release binaries of MD-CMS for Linux, macOS and Windows. This document is relevant for you who want to continue developing MD-CMS  on your own.

## Prerequisites

- Push access to your GitHub release repository
- 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. Go to **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 at least places:

**`mdcms.py`** — find this line near the top and bump it:
```python
CLI_VERSION = "0.3.8"
```

**`pyproject.toml`** — bump the matching line:
```toml
version = "0.3.8"
```

If you have made changes that affect the `index.html` and/or `config.yml`, update the minimum supported version comment at the top of each file:

**`app/index.html`** — bump the matching line:
```html
<!-- Minimum supported version: mdcms v0.3.8 | DO NOT REMOVE THIS COMMENT -->
```

**`app/config.yml`** — bump the matching line:
```yml
# Minimum supported version: mdcms v0.3.2 | DO NOT REMOVE THIS COMMENT
``` 


#### Commit locally
Commit the version bump:
```bash
git add mdcms.py pyproject.toml
git commit -m "Bump version to 0.3.8"
git push origin main
```
#### Commit on the web
Save each file with a version bump notice: `"Bump version to 0.3.8"`.

### Tagging the release

#### Locally
Push a version tag to trigger the workflow:
```bash
git tag v0.3.8
git push origin v0.3.8
```
#### On the web

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

The binaries will be generated by 

#### 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:
```bash
git tag -d v0.3.8
git push origin --delete v0.3.8
```

Fix the issue, then re-tag:
```bash
git tag v0.3.8
git push origin v0.3.8
```

## 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

## Follow-up
If you serve `latest` binaries from a standard URL, you also have to make sure to update these.
