Fixing problems

Whichever process is followed, some problems and the way to solve them are similar. After getting familiar with the process(es), this section describes them.

The documents on each process describe problems and solutions unique to them.

Unsatisfiable dependencies

When there are unsatisfiable dependencies, dpkg-checkbuilddeps will fail. It might be missing dependencies, version mismatches, or both.

For missing dependencies, check if they are mandatory. If so, package them first. If optional, and functionalities requiring them are less than important, they could be temporarily disabled to ease initial packaging. See how to disable them.

For version mismatches, first check if simply relaxing the version constraints would do:

Sometimes it's a patch or minor level version too high, e.g. when dependency foo 1.2.3 is required, while we only have 1.2.1 on Debian. This is the simplest case; just patch the version constraint to be 1.2.1, or even simpler, 1.2.
Sometimes it's a major version mismatch, e.g. foo 2 is required but only 1 is in Debian. In this case, first check if patching it to use foo 1 would work. If so, just go with that; if not, try downgrading it. If that's too hard, try upgrading foo to 2. Sometimes it's the other way around: foo 1 is required but 2 is in Debian. Then there's one more option: asking upstream to upgrade.
If the last point didn't work, you can probably consider splitting out a versioned package. But ask the team before doing so.

Note: major version changes usually mean a transition, which needs coordination in and sometimes out of the team, unless affected are few and it's easy to migrate all of them in sync.

Update dependencies

In some cases, old versions of some dependencies are still used. To limit the number of duplicated libraries in the archive, please try to evaluate if a newer version of the dependencies could be used.

This is done by patching Cargo.toml to use the newer version.

Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds with no further source changes, then change the required version in Cargo.toml from 0.3 to >= 0.3, < 0.6 or something like that. Then the convention is to put all these changes into a single patch called relax-deps.patch.

OTOH, if the cargo build fails, and you can fix it by editing the source code in a minor way to use the new crate API, then for each crate that needs to be updated, you should instead name the patch relax-dep-<crate>.patch, and add changes of both the relevant entry in Cargo.toml and the source code to it. The change to Cargo.toml should then simply say, for the above example, 0.5, since the older versions in the range >= 0.3, < 0.6 won't work.

If you want to make a crate work with an older dependency version than listed in Cargo.toml (for example 0.3 instead of 0.5), you cannot use a flexible version requirement like >= 0.3, < 0.6. Instead you have to specify only the older version, in this example 0.3.

An explanation for the version range thing was given by Ximin Luo (infinity0) in a merge request:

It's a quirky annoyance of sbuild/apt (I can't remember which) that for build-depends only the first in a series of alternatives is considered, and yes in these sorts of situations we are in fact forced to downgrade the dependency version.

The authors refused to fix it the last time I spoke to them about this, giving the incorrect reasoning "it would mess with build reproducibility". The reasoning is incorrect because by the same argument one should not allow different versions of the same compiler, and when doing reproducibility (which I worked, paid, on several years ago) one is supposed to record the actually-installed versions of the build-depends and use these exact same ones when attempting a 2nd reproduction, otherwise one cannot expect reproducibility anyways.

Failing patches

As upstream releases new versions, patches become out of date and fail to apply. You should refresh/update applicable patches, drop outdated/obsolete ones, introduce new ones as failures occur.

There are several ways to manage patches: quilt, gbp-pq, etc. In workspace process, the maintainer is free to use any they see fit. In single crate process, due to its monorepo nature, and the particular way files are organized, options are limited. See the process document for details.

Breaking changes due to changed version

When a dependency is patched to upgrade or downgrade, there are likely breaking changes. Consult docs of the corresponding dependency, including docs.rs (https://docs.rs/<crate>/<version>) and their changelogs (some maintain a CHANGELOG.md in the repo, some record in GitHub Releases notes).

Test failures

Sometimes, tests require extra tweaks and settings to work. Edit the corresponding test definitions. For single crate process, this means copying build/<crate>/debian/tests/control over to src/<crate>/debian/tests/.

Sometimes, the tests fail, due to missing test data/fixtures, no network access in buildds or debci runners, feature combinations not considered by upstream, etc. You can patch them out: see General tips.

Alternatively, for (1) the tests can be disabled by running dh_auto_test -- build instead of dh_auto_test -- test --all in debian/rules, and for (2) they can be marked broken ("flaky"). They are still run by autopkgtest, but their failing is no longer considered an error.

For workspace process, add Restriction: flaky to the test case.

For single crate process, add this to debcargo.toml:

[packages."lib+feature"] ## --no-default-features --features feature
test_is_broken = true

[packages.lib] # --no-default-features
test_is_broken = true

[packages."lib+@"] # --all-features
test_is_broken = true

Note that marking packages.lib.test_is_broken = true (i.e. --no-default-features) will transitively disable tests for all combinations of features. Sometimes this is correct e.g. if the test actually breaks for all features. Sometimes this is not correct, e.g. if the test only breaks for --no-default-features. In the latter case you should instead patch the crate to ignore those tests when the relevant features are absent.

Debug info & backtrace

Sometimes, the error messages are not the most informative. In this case you can try re-running the command with RUST_BACKTRACE=1.

If you are following the single crate process, and using the debcargo from Debian's own repositories, you should also install the debcargo-dbgsym package, which includes debug symbols for debcargo. Otherwise backtraces of itself could be less useful. Make sure you have the debug repository enabled in your apt sources.