Skip to content

Release Workflow

Jump to bottom
Fabio Scaccabarozzi edited this page Aug 29, 2026 · 2 revisions

Release Workflow

End-to-end sequence for moving the overlay to a new cosmic-epoch tag.

1. Start from a clean, up-to-date main 

git switch main
git pull
git clean -dfx
git reset --hard HEAD

2. Branch out

git switch -c feature/<version>

Every release bump goes through a feature branch + PR — never commit a release bump directly to main.

3. Run the bump

./scripts/bump_and_qa_ebuild.sh -v epoch-<version>

4. Resolve any failures

See Bumping Ebuilds for the retry loop (reproduce with ebuild ... prepare/compile/install, diff against the previous version and against -9999, re-run the script with -p <pkg> for just that package — there's no resume mode, so a bare re-run reprocesses everything).

5. Check upstream for changes the script won't catch

The bump script updates ebuild boilerplate, but it won't tell you about behavioral changes upstream made. For each package that changed non-trivially, check the cosmic-epoch release notes and diff the relevant submodule between tags for:

  • Justfile changes — install paths, new install targets, renamed recipes
  • Cargo.toml changes — new/removed system dependencies, feature flags

Port anything relevant into the ebuild by hand (e.g. a new file the Justfile now installs needs a matching line in src_install).

6. Test and QA

emerge -uDN @world --quiet --keep-going

This actually builds and installs every touched package on the test VM, which is what proves the bump works — a pkgcheck scan alone doesn't (see the caveat in QA and Testing). Run it alongside a static check for obvious mistakes:

python3 scripts/simple-qa-check.py

7. Push the feature branch

git push --set-upstream origin feature/<version>

8. Drop the superseded ebuilds

The overlay keeps the current and previous tagged version around; once the new version is green, drop the version two releases back (VERSION-2):

find -iname "*<version-2>*.ebuild" -delete
./scripts/digests_and_cache.sh   # re-runs `ebuild manifest` for every package, dropping the now-unreferenced tarball hash lines
git commit -a -m "drop <version-2>"

9. Open the PR

Title/description as a short changelog, e.g.:

add 1.7.0, drop 1.5.0
- fix cosmic-comp OSD crash on wayland (backport #142)
- ...

10. Review the PR

A clean release-bump PR should look mechanical, per package:

  • 1 file moved: <pkg>-<version-2>.ebuild deleted, <pkg>-<version>.ebuild added
  • Manifest: 1 line removed (old tarball hash), 1 line added (new tarball hash)
  • plus any extra, clearly-scoped fixes from step 5

If a package's diff looks like more than that without an obvious reason, that's worth a second look before merging — it usually means something didn't bump cleanly.

11. Merge

Once CI (qa-check.yml) is green on the PR, merge it.

Notes on versioning

  • The overlay version is the cosmic-epoch tag with the epoch- prefix dropped (epoch-1.4.0 → 1.4.0).
  • -r<N> is reserved for overlay-only patch bumps (a backport, an ebuild fix) — never for upstream source changes. Don't reach for -r1 just because a new tag exists; that's a new PV.
  • New packages (e.g. cosmic-monitor, cosmic-sound-theme when they were split out upstream) get added the same way as any other bump target — see Adding and Updating Packages for the --create flow.

Clone this wiki locally