cargo-util: update to 0.2.2

[debcargo-conf.git] / README.rst

diff --git a/README.rst b/README.rst
index 89f48b741132c7baae826212d7646400b917ceeb..7b2fa6bb5f8fdc6852e885e7f789dec1034404bc 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -34,6 +34,17 @@ and follow its instructions. To save time, you can first copy anything relevant
 from ``src/<rust-crate-name>`` to ``src/<rust-crate-name>-<old-version>``, then
 adapt it as needed.
 
+You will need excellent reasons to do this. It should be done only for core crates
+used by many other crates or programs for which the upgrade path is complex.
+For example, if the API significantly changed and requires a lot of work.
+
+Instead, please consider:
+* Downgrading or upgrading the dependency.
+* If it doesn't exist, open an issue on the upstream issue tracker to
+  encourage them to upgrade.
+* If possible/relevant, disable a feature if it uses it.
+* Wait until upstream upgraded.
+
 To prepare a release
 --------------------
 
@@ -86,6 +97,9 @@ To set up a suitable build environment for ``./build.sh``::
 An explanation of this, plus more recipes, can be found on the `sbuild wiki
 page <https://wiki.debian.org/sbuild>`_.
 
+If you need to pass additional options to sbuild, like "--arch=i386", then set
+the SBUILD_OPTS environment variable.
+
 Normally, ``./build.sh`` will fail early if not all the build dependencies are
 available in your local apt cache. If you are packaging a large dependency tree
 however, to avoid many round-trips through NEW it is possible to bypass this
@@ -101,7 +115,11 @@ A, then you can run something like::
 
 The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
 sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
-been built by the previous step.
+been built by the previous step. Alternatively, use the environment variable
+``EXTRA_DEBS``, like so: ::
+
+  $ EXTRA_DEBS=librust-A*.deb ./build.sh B
+  $ EXTRA_DEBS=librust-A.deb,librust-B.deb ./build.sh C
 
 After everything is built successfully, you can ``dput`` all of them and then
 push all the ``pending-*`` branches as normal.
@@ -223,6 +241,30 @@ conditions for (2), e.g. https://github.com/hsivonen/simd/issues/25
 obvious so documentation is less necessary, and dependent crates all do it
 correctly already.)
 
+Setting collapse_features in debcargo.conf
+------------------------------------------
+
+Rust and Debian have a two different levels of abstraction when handling dependencies and the
+relationship between them. In rust the lowest level is a feature, and in Debian it's the binary
+package.
+
+This means that the following dependency chain is not a problem in rust:
+
+- crate A with feature AX depends on crate B with feature BY
+- crate B with feature BX depends on crate A with feature AY
+
+This is a perfectly valid situation in the rust+cargo ecosystem. Notice that
+there is no dependency cycle on the per-feature level, and this is enforced by
+cargo; but if collapse_features is used then package A+AX+AY would cyclicly
+depend on package B+BX+BY.
+
+This is reflected in the Debian packages by producing `Provides` lines for all combinations
+of features, and this can become a quite large section.
+
+Setting `collapse_features = true` in debcargo.toml removes this behaviour and is recommended,
+but it can lead to dependency cycles of debian packages, if that happens those must be
+broken up by having some or all of the packages set this feature to false.
+
 Changed orig tarballs
 ---------------------
 
@@ -241,7 +283,7 @@ Don't file ITPs for library crates, but do file them for binary crates.
 Generally we'll be uploading a dozen crates or so at once. Submitting ITPs for
 these is unnecessary since we're the only ones uploading and there is no chance
 of conflict. It would only be spam for the bug tracker. Please instead
-co-ordinate uploads on the ``#debian-rust`` IRC channel.
+coordinate uploads on the ``#debian-rust`` IRC channel.
 
 Testing
 -------