# Releasing

Homebase 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/homebase/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. **Create a Forgejo Release** at `https://forgejo.sourcegate.online/daniel/homebase/releases/new`:
   - Tag: `26.1-alpha` (already exists)
   - Title: `26.1-alpha`
   - Body: paste the changelog section for this version
   - Tick **Pre-release** for anything still `-alpha` or `-beta`

6. **Verify CI passed on the tag.** The Forgejo Actions run against the tagged commit should be green before you announce the release anywhere.

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