-Versioning
-==========
+Local cargo config
+==================
-Note that the following applies *per crate*, since each crate is its own debian package:
+This repository ships with a ``.cargo/config`` that replaces the crates.io
+registry with packaged crates located in ``/usr/share/cargo/registry``.
-The first commit after a release should bump the version to the next patch level with a ``-dev.1``
-suffix for the crate *and for the proxmox crate*, as well as all crates depending on it. For
-instance, ``proxmox-api`` depends on ``proxmox-tools``, so bumpgin ``proxmox-tools`` to a new `dev`
-version also requires bumping ``proxmox-api`` to a new dev version, since cargo requires
-pre-release versions to be selected explicitly:
+A similar config is also applied building with dh_cargo. Cargo.lock needs to be
+deleted when switching between packaged crates and crates.io, since the
+checksums are not compatible.
+
+To reference new dependencies (or updated versions) that are not yet packaged,
+the dependency needs to point directly to a path or git source.
+
+Steps for Releases
+==================
- First commit after release: 0.1.0 -> 0.1.1-dev.1
- Version bump commit: 0.1.1-dev.1 -> 0.1.1
+- Run ./bump.sh <CRATE> [patch|minor|major|<VERSION>]
+-- Fill out changelog
+-- Confirm bump commit
+- Build packages with `make deb`.
+-- Don't forget to commit updated d/control!
-It is unlikely that we'll need more than one .dev version, but it may be useful at some point, so
-we'll include teh ``.1``.
+Adding Crates
+=============
-When releasing a crate, the final commit should be the one stripping the ``-dev`` version and
-updating the ``debian/changelog``.
+1) At the top level:
+ - Generate the crate: ``cargo new --lib the-name``
+ - Sort the crate into ``Cargo.toml``'s ``workspace.members``
-Local (packaged) crates
+2) In the new crate's ``Cargo.toml``:
+ - In ``[package]`` set:
+ authors.workspace = true
+ license.workspace = true
+ edition.workspace = true
+ exclude.workspace = true
+ repository.workspace = true
+ - Add a meaningful ``description``
+ - Copy ``debian/copyright`` and ``debian/debcargo.toml`` from another subcrate.
+
+Adding a new Dependency
=======================
-To use locally installed, packaged crates instead of crates.io put the
-following into ./.cargo/config (or point CARGO_HOME to a directory containing
-such a config file)::
+1) At the top level:
+ - Add it to ``[workspace.dependencies]`` specifying the version and any
+ features that should be enabled throughout the workspace
- [source]
- [source.debian-packages]
- directory = "/usr/share/cargo/registry"
- [source.crates-io]
- replace-with = "debian-packages"
+2) In each member's ``Cargo.toml``:
+ - Add it to the desired dependencies section with ``workspace = true`` and no
+ version specified.
+ - If this member requires additional features, add only the extra features to
+ the member dependency.
-This is akin to what happens when building with dh_cargo. Cargo.lock needs to
-be deleted when switching between packaged crates and crates.io, since the
-checksums are not compatible.
+Updating a Dependency's Version
+===============================
+
+1) At the top level:
+ - Bump the version in ``[workspace.dependencies]`` as desired.
+ - Check for deprecations or breakage throughout the workspace.
+
+Notes on Workspace Inheritance
+==============================
+
+Common metadata (like authors, license, ..) are inherited throughout the
+workspace. If new fields are added that are identical for all crates, they
+should be defined in the top-level ``Cargo.toml`` file's
+``[workspace.package]`` section, and inherited in all members explicitly by
+setting ``FIELD.workspace = true`` in the member's ``[package]`` section.
+
+Dependency information is also inherited throughout the workspace, allowing a
+single dependency specification in the top-level Cargo.toml file to be used by
+all members.
+
+Some restrictions apply:
+- features can only be added in members, never removed (this includes
+ ``default_features = false``!)
+ - the base feature set at the workspace level should be the minimum (possibly
+ empty!) set required by all members
+- workspace dependency specifications cannot include ``optional``
+ - if needed, the ``optional`` flag needs to be set at the member level when
+ using a workspace dependency
projects / proxmox.git / blobdiff