Troubleshooting

Troubleshooting

Recurring issues from actual bump sessions, and how they were resolved.

cargo vendor fails because Cargo.lock wasn't bumped upstream

Upstream sometimes tags a release without bumping Cargo.lock to match. cargo vendor --locked then fails. Fix:

./scripts/bump_and_qa_ebuild.sh -v epoch-<version> -p <pkg> --allow-non-frozen-vendoring

Use this narrowly (single package, not a blanket default) — it's a signal upstream's lockfile is out of sync, worth flagging upstream if it recurs.

Eclass function/variable renamed, old ebuilds still reference it

Symptom: a package that used to bump cleanly suddenly fails prepare/compile referencing a function that "doesn't exist." Usually means the eclass was refactored (e.g. cosmic-de-r2_target_dir → cosmic-common_target_dir, cosmic-de-r2_install_metainfo → cosmic-common_install_metainfo) and the generated ebuild wasn't regenerated from a fresh template. Fix with a targeted repo-wide sed rather than editing each ebuild by hand:

grep -ri '_target_dir' */*/*-<version>.ebuild   # find current call sites first
sed -i -e 's:cosmic-de-r2_target_dir:cosmic-common_target_dir:' */*/*-<version>.ebuild

A wrong variable slipped past pkgcheck

pkgcheck scan is a static check — it won't catch a variable that's syntactically valid but semantically wrong (e.g. a leftover reference from a copy-pasted ebuild pointing at the wrong package's build dir). The only reliable catch is actually running the affected phases:

ebuild <pkg>-<version>.ebuild clean unpack prepare
ebuild <pkg>-<version>.ebuild compile
ebuild <pkg>-<version>.ebuild install

For packages known to be copy-paste-derived from a sibling (see Adding and Updating Packages), diff against the sibling as an extra check.

Leftover temp directories eating disk

The bump script keeps its temp working directory by default purely so you can inspect it after a run — there's no resume mode that depends on it (see Bumping Ebuilds). If a VM has several left over:

rm -rf /var/tmp/cosmic-bump.*
# or, for the current version's run specifically:
./scripts/bump_and_qa_ebuild.sh epoch-<version> --clean-temp

The script uses /var/tmp rather than /tmp specifically to avoid tmpfs-backed /tmp running out of space during vendoring — don't override TMPDIR to point back at /tmp on constrained VMs.

PATCHES entry commented out by the bump script

The script auto-comments a PATCHES line if applying it fails against the new source, rather than silently dropping it — this is intentional, not a bug. It means the patch needs to be regenerated against the new tag. See "Manual patches / backports" in Bumping Ebuilds.

Confusing PVR vs PV in SRC_URI

If an ebuild's SRC_URI references ${PVR} instead of ${PV}, an overlay-only revision bump (-r1) will unexpectedly try to fetch a different upstream source instead of just re-packaging with a fix. This was fixed repo-wide (SRC_URI should always use PV; -rX is for overlay-only changes and must never affect the fetched tarball) — if you see a new package reintroduce PVR in SRC_URI, treat it as a bug, not a style choice.

PR diff looks bigger than expected for a routine bump

A clean per-package bump diff is mechanical: one ebuild file moved (old version deleted, new version added) plus a two-line Manifest swap (old tarball hash removed, new one added). If a package's diff is larger than that with no corresponding entry in your upstream Justfile/Cargo.toml review (see Release Workflow step 5), something likely didn't bump cleanly — re-check it before merging rather than assuming it's fine.