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::
REALVER=<old-version> ./update.sh <rust-crate-name> # then
REALVER=<old-version> ./release.sh <rust-crate-name>
+Repackaging the existing revision
+---------------------------------
+
+In order to build a package A already in ``debcargo-conf/src``
+in the exact version which is present here, do the following::
+
+ $ ./repackage.sh A
+ $ cd build
+ $ ./build.sh A
+
+If this package is already in the archive and you want to recreate that
+exactly, you will need to use the exact same version of debcargo that was
+used previously. This version is mentioned in ``debian/changelog``.
+
+
+Repository structure
+====================
+
+`pending-*` branches are managed by `./release.sh`, so please don't manage them
+yourself as you will interfere with the working of that script. The intention
+is that they should only differ from the master branch by 1 commit, i.e. the
+`dch -r` commit created by `./release.sh`.
+
+If you want to create separate non-master branches, that is fine - just don't
+call them `pending-*` and don't run `./release.sh` on those branches. If you
+want to test your crate, instead run::
+
+ cd build && [SOURCEONLY=1] ./build.sh <rust-crate-name> [<old-version>]
+
+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
+=================
+
+To set up a suitable build environment for ``./build.sh``::
+
+ $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
+ $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
+ --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
+check and build all the packages together. Suppose package B depends on package
+A, then you can run something like::
+
+ $ export IGNORE_MISSING_BUILD_DEPS=1
+ $ ./release.sh A
+ $ ( cd build && ./build.sh A )
+ # push pending and checkout master
+ $ ./release.sh B
+ $ ( cd build && ./build.sh B librust-A*.deb )
+
+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.
+
+After everything is built successfully, you can ``dput`` all of them and then
+push all the ``pending-*`` branches as normal.
+
General packaging tips
======================
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"
+------------------------------------
+
+See ``src/dotenv`` for an example on dealing with this.
+
+Binary-crate has conflicting name
+---------------------------------
+
+See ``src/fd-find`` for an example on dealing with this.
Updating the dependencies
-------------------------
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.
-
-
-DD instructions
-===============
-
-To set up a suitable build environment for ``./build.sh``::
-
- $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
- $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
- --chroot-prefix debcargo-unstable unstable \
- /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
-
-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
-check and build all the packages together. Suppose package B depends on package
-A, then you can run something like::
-
- $ export IGNORE_MISSING_BUILD_DEPS=1
- $ ./release.sh A
- $ ( cd build && ./build.sh A )
- # push pending and checkout master
- $ ./release.sh B
- $ ( cd build && ./build.sh B librust-A*.deb )
-
-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.
-
-After everything is built successfully, you can ``dput`` all of them and then
-push all the ``pending-*`` branches as normal.
+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