README.rst

   1 Local cargo config
   2 ==================
   3
   4 This repository ships with a ``.cargo/config`` that replaces the crates.io
   5 registry with packaged crates located in ``/usr/share/cargo/registry``.
   6
   7 A similar config is also applied building with dh_cargo. Cargo.lock needs to be
   8 deleted when switching between packaged crates and crates.io, since the
   9 checksums are not compatible.
  10
  11 To reference new dependencies (or updated versions) that are not yet packaged,
  12 the dependency needs to point directly to a path or git source.
  13
  14 Steps for Releases
  15 ==================
  16
  17 - Run ./bump.sh <CRATE> [patch|minor|major|<VERSION>]
  18 -- Fill out changelog
  19 -- Confirm bump commit
  20 - Build packages with `make deb`.
  21 -- Don't forget to commit updated d/control!
  22
  23 Adding Crates
  24 =============
  25
  26 1) At the top level:
  27   - Generate the crate: ``cargo new --lib the-name``
  28   - Sort the crate into ``Cargo.toml``'s ``workspace.members``
  29
  30 2) In the new crate's ``Cargo.toml``:
  31   - In ``[package]`` set:
  32       authors.workspace = true
  33       license.workspace = true
  34       edition.workspace = true
  35       exclude.workspace = true
  36       repository.workspace = true
  37   - Add a meaningful ``description``
  38   - Copy ``debian/copyright`` and ``debian/debcargo.toml`` from another subcrate.
  39
  40 Adding a new Dependency
  41 =======================
  42
  43 1) At the top level:
  44   - Add it to ``[workspace.dependencies]`` specifying the version and any
  45     features that should be enabled throughout the workspace
  46
  47 2) In each member's ``Cargo.toml``:
  48   - Add it to the desired dependencies section with ``workspace = true`` and no
  49     version specified.
  50   - If this member requires additional features, add only the extra features to
  51     the member dependency.
  52
  53 Updating a Dependency's Version
  54 ===============================
  55
  56 1) At the top level:
  57   - Bump the version in ``[workspace.dependencies]`` as desired.
  58   - Check for deprecations or breakage throughout the workspace.
  59
  60 Notes on Workspace Inheritance
  61 ==============================
  62
  63 Common metadata (like authors, license, ..) are inherited throughout the
  64 workspace. If new fields are added that are identical for all crates, they
  65 should be defined in the top-level ``Cargo.toml`` file's
  66 ``[workspace.package]`` section, and inherited in all members explicitly by
  67 setting ``FIELD.workspace = true`` in the member's ``[package]`` section.
  68
  69 Dependency information is also inherited throughout the workspace, allowing a
  70 single dependency specification in the top-level Cargo.toml file to be used by
  71 all members.
  72
  73 Some restrictions apply:
  74 - features can only be added in members, never removed (this includes
  75   ``default_features = false``!)
  76  - the base feature set at the workspace level should be the minimum (possibly
  77    empty!) set required by all members
  78 - workspace dependency specifications cannot include ``optional``
  79  - if needed, the ``optional`` flag needs to be set at the member level when
  80    using a workspace dependency