Note that ``new-package.sh`` is just a symlink to ``update.sh``, to help newcomers.
-To package an older version of a crate
---------------------------------------
+To package a co-installable older version of a crate
+----------------------------------------------------
To maintain an old version of a crate alongside the latest one, first make sure
the latest version is packaged by doing all of the above, then run::
omitting or not omitting the stuff in [] as needed.
+Like many other Debian git repositories, we don't follow "feature branch"
+practises here. We generally don't package just 1 or 2 rust crates at a time,
+but all of its dependencies and sometimes some reverse-dependencies too. So
+normally we'll be touching a few dozen packages at once. In this context, it's
+good to merge often, to avoid conflicts with someone else that might also need
+to touch those too in the next few days.
+
+To match a release (i.e. a ``.deb`` or a ``.dsc`` file) to a commit, find the
+commit message that actually says "Release package X". This will usually be a
+merge commit.
+
Build environment
=================
--chroot-prefix debcargo-unstable unstable \
/srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
+An explanation of this, plus more recipes, can be found on the `sbuild wiki
+page <https://wiki.debian.org/sbuild>`_.
+
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
the tarball was updated and its behaviour changed - compression settings,
tarball archive ordering, etc. This will cause your upload to get REJECTED by
the Debian FTP archive for having a different orig.tar. In this case, set
-REUSE_EXISTING_ORIG_TARBALL=1 when running ``./release.sh``.
+``REUSE_EXISTING_ORIG_TARBALL=1`` when running ``./release.sh``.
ITPs
----
Don't file ITPs for library crates, but do file them for binary crates.
-For now (updated 2018-09) we have several hundred crates to upload. 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.
+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.
Testing
-------
-For now, testsuites aren't executed for library.
-However, for binary, it is strongly recommended to run the testsuites.
-See ripgrep as example.
+Debian has two types of tests:
+
+1. pre-install tests run in ``debian/rules``
+2. post-install tests defined in ``debian/tests/control``
+
+For Debian rust packages, in (1) we run the crate's test suite with default
+features but only if there are no dev-dependencies, and in (2) we run the whole
+test suite with each feature enabled separately plus ``--no-default-features``
+and ``--all-features``.
+
+Sometimes, tests require extra tweaks and settings to work. In this case, you
+can tweak ``debian/rules`` for (1), and for (2) you will simply have to mark
+the relevant tests as broken using ``test_is_broken = true``. See the existing
+crate configs for examples.
+
+Other times, the tests are simply broken or can't be run in Debian. In this
+case you should disable the test in (1) by running ``dh_auto_test -- build``
+instead of the default ``dh_auto_test -- test --all``, and for (2) again you
+should mark the relevant tests as broken.
+
+Please note that ``[packages.lib]\ntest_is_broken = true`` 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 - e.g. ``src/regex-automata/debian/patches/ignore-std-tests.patch``.
Binary-crate has "required-features"
------------------------------------
archive, please try to evaluate if a newer version of the dependencies could be
used.
-To achieve that, after ./update.sh, try::
+To achieve that, after ``./update.sh``, try::
$ cd build/<package>/
$ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
OTOH, if the cargo build fails, and you can fix it up 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 ``update-dep-<crate>.patch``
-and add both the ``Cargo.toml`` and the source code changes to it. Use
-``quilt rename`` if that helps you.
+and add both the ``Cargo.toml`` and the source code changes to it. The change
+to ``Cargo.toml`` would then simply say (e.g.) ``0.5`` since the older versions
+actually don't work, and not the version range from the previous paragraph.
+
+Help, something went wrong!
+---------------------------
+
+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 using the
+``debcargo`` from Debian's own repositories, you should also install the
+``debcargo-dbgsym`` package, otherwise the stack trace will be next to useless.
+Make sure you have the `debug repository <https://wiki.debian.org/HowToGetABacktrace#Installing_the_debugging_symbols>`_
+enabled in your APT sources.
projects / debcargo-conf.git / blobdiff