[proxmox.git] / README.rst

Local cargo config
==================

This repository ships with a ``.cargo/config`` that replaces the crates.io
registry with packaged crates located in ``/usr/share/cargo/registry``.

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
==================

- 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
Commit	Line	Data
	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