Merge branch 'proxmox-acme'

[proxmox.git] / README.rst

diff --git a/README.rst b/README.rst
index 12deebba1f89120424a8e3ebfd74eb0015b895c5..2288f797a9cff260a04a909f1f249717520fe55c 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -14,9 +14,67 @@ the dependency needs to point directly to a path or git source.
 Steps for Releases
 ==================
 
-- Cargo.toml updates:
-  - Bump all modified crate versions.
-  - Update all the other crates' Cargo.toml to depend on the new versions if
-    required, then bump their version as well if not already done.
-- Update debian/changelog files in all the crates updated above.
+- 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!
+
+Adding Crates
+=============
+
+1) At the top level:
+  - Generate the crate: ``cargo new --lib the-name``
+  - Sort the crate into ``Cargo.toml``'s ``workspace.members``
+
+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
+=======================
+
+1) At the top level:
+  - Add it to ``[workspace.dependencies]`` specifying the version and any
+    features that should be enabled throughout the workspace
+
+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.
+
+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