Maintainer Guide

Maintainer Guide

Main entry point for day-to-day overlay maintenance. Start here, then drill into the page that matches what you're doing:

• Bumping Ebuilds — the release-bump workflow (scripts/bump_and_qa_ebuild.sh), what to do when it fails on a package, and how to backport/patch manually
• QA and Testing — local QA tools, what CI runs, and how to read the reports
• Release Workflow — end-to-end sequence for cutting a new overlay release against a cosmic-epoch tag, including cleanup of old versions
• Adding and Updating Packages — creating a brand-new package vs. bumping an existing one, and the non-COSMIC toolchain packages (dev-lang/dart, dev-util/buf, dev-util/dart-sass*, x11-themes/adw-gtk3, ...)
• Troubleshooting — recurring failure patterns and how they were fixed in practice

Ground rules

• Test on the Gentoo VM, not locally. The overlay is checked out at /var/db/repos/cosmic-overlay on the test VM; edits made on a dev machine should be synced there (scp/rsync/push+pull) before running ebuild/emerge/pkgcheck against them.
• Release bumps always go through a feature branch + PR, never a direct commit to main — see Release Workflow. Start from a clean, up-to-date main (git clean -dfx, git reset --hard HEAD) before branching.
• One package, one commit. Whether via the bump script or manually, keep commits scoped to a single package so history stays bisectable and reverts stay cheap.
• The overlay keeps the current and previous tagged version, dropping the version two releases back (VERSION-2) once a new one lands — see Release Workflow.
• Eclass changes are high blast-radius. cosmic-de-r2.eclass / cosmic-live.eclass are inherited by nearly every package in cosmic-base — see Architecture. Test against a handful of representative packages (a GUI app, a daemon, a meta-package) before assuming a change is safe.
• Prefer the automation, but don't fight it. bump_and_qa_ebuild.sh handles the common path end to end; when a package needs something the script doesn't support (a manual patch, a one-off ebuild tweak), drop to manual ebuild ... prepare/compile/install commands for that package, then re-run the script with -p <pkg> for just that one. There's no resume mode — a bare re-run reprocesses everything, so always retry with -p.
• Touching IUSE means touching metadata.xml too. Adding, renaming, or removing a USE flag on a package requires a matching update to that package's <use> block in metadata.xml — pkgcheck will flag a mismatch, but check it yourself rather than relying on CI to catch it.

Community

Join the COSMIC Mattermost (chat.pop-os.org) to stay in touch with upstream COSMIC developers and other distro maintainers:

• #cosmic-epoch — general COSMIC development
• #cosmic-distro-maintainers — especially useful: distro packagers comparing notes, early word on upstream breaking changes, and a place to ask before assuming an issue is overlay-specific