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.**
   ```markdown
   ## [Unreleased]

   ## [26.1-alpha] - 2026-05-20
   ### Added
   - ...
   ```
   Add a `[26.1-alpha]` link definition at the bottom:
   ```markdown
   [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.**
   ```bash
   git add CHANGELOG.md
   git commit -m "chore: release 26.1-alpha"
   ```

3. **Tag the commit.**
   ```bash
   git tag -a 26.1-alpha -m "Release 26.1-alpha"
   ```

4. **Push the tag and main.**
   ```bash
   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`). The ISO gets a `furtka-<ver>.iso.sha256` sidecar, and a last step rebuilds furtka.org so the download page (`/download/`) picks up the new ISO, size, date and checksum from the Forgejo API. 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

```bash
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.

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