furtka/RELEASING.md

Releasing

Furtka uses calendar versioning: YY.N-stage — e.g. 26.0-alpha is 2026, release 0, alpha stage. No v prefix.

• YY — last two digits of the current year
• N — incrementing release number within the year, starting at 0 (next one in 2026 is 26.1-alpha, then 26.2-alpha…)
• -alpha — drop it when the installer boots end-to-end and wipe-and-reinstall is safe

When the year rolls over, the next release becomes 27.0-alpha regardless of how many 26.x releases shipped.

Cadence

Tag per meaningful milestone, not on a calendar. A milestone is: ISO boots, a wizard screen works end-to-end, managed gateway serves its first real domain, etc. If a week goes by with no tag, that's fine — no tag is better than a noisy one.

Release steps

1. Move [Unreleased] in CHANGELOG.md to a new version heading.

   ## [Unreleased]
   
   ## [26.1-alpha] - 2026-05-20
   ### Added
   - ...
   

   Add a [26.1-alpha] link definition at the bottom:

   [26.1-alpha]: https://forgejo.sourcegate.online/daniel/furtka/releases/tag/26.1-alpha
   

   Update the [Unreleased] compare link to point at the new tag.

2. Commit the changelog.

   git add CHANGELOG.md
   git commit -m "chore: release 26.1-alpha"
   

3. Tag the commit.

   git tag -a 26.1-alpha -m "Release 26.1-alpha"
   

4. Push the tag and main.

   git push origin main
   git push origin 26.1-alpha
   

5. The release workflow does the rest. .forgejo/workflows/release.yml fires on the tag push and runs on the self-hosted runner: scripts/build-release-tarball.sh builds the self-update payload (tarball + sha256 + release.json under dist/), iso/build.sh builds the live-installer ISO, scripts/publish-release.sh uploads tarball + sha256 + release.json + ISO to the Forgejo release page. Pre-release is flagged automatically based on the suffix (-alpha/-beta/-rc). ISO build is continue-on-error: a flaky ISO step doesn't block the core tarball (the thing boxes need for self-update).

   The release workflow needs one secret set at repo Settings → Secrets → Actions:

   • FORGEJO_RELEASE_TOKEN — a PAT with write:repository scope.

6. Verify CI passed on the tag. The Forgejo Actions run against the tagged commit should be green before you announce the release anywhere — both the CI workflow (lint/test) and the Release workflow (tarball published).

7. (Optional) Dogfood the update path. On a VM running the previous version, sudo furtka update --check should now see the new tag, and sudo furtka update applies it without a reinstall.

First-time: find the current version

git describe --tags --abbrev=0

If the project is fresh and git describe fails, the next release is 26.0-alpha.

If the tag is wrong

Don't move published tags. Delete the release + tag, fix the problem, bump to the next number.

git tag -d 26.1-alpha
git push origin :refs/tags/26.1-alpha
# ... fix ...
git tag -a 26.2-alpha ...