mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# 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.
|