mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
kbenestad
0d0dfa7268
This guide provides detailed steps for releasing a new version of mdcms, including prerequisites, setup, version bumping, tagging, and monitoring the build process.
92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# 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
|