diff options
| -rw-r--r-- | README.md | 11 | ||||
| -rw-r--r-- | doc/Semver.md | 61 | ||||
| -rw-r--r-- | doc/dev/Release.md | 46 |
3 files changed, 110 insertions, 8 deletions
@@ -148,6 +148,17 @@ That library's API will allow you to make connections over the Tor network, and obtain streams/sinks usable from async Rust. +We make fairly frequent semver bumps the Arti library API, +and to our lower-level crates. +However, in practice, we don't often make disruptive changes +that aren't easy to sort out in a dependency. +When using Arti as a library, you should be prepared to make regular updates, +bumping your versions requirement, not just `cargo update`. +`cargo upgrade` can help with this. + +See [our version update and API compatibility policy](doc/Semver.md) +for more details. + ## Minimum supported Rust Version Our current Minimum Supported Rust Version (MSRV) is 1.70. diff --git a/doc/Semver.md b/doc/Semver.md new file mode 100644 index 000000000..06fa3a8f7 --- /dev/null +++ b/doc/Semver.md @@ -0,0 +1,61 @@ +# Stability and semver, for crates which are part of the Arti Project + +This policy applies to all crates which are part of +[the `arti` repository](https://gitlab.torproject.org/tpo/core/arti). +Other crates maintained by the Tor Project may have different policies. + +## Rust and cargo semver + +We will honour the usual Rust conventions about semver stability: +whenever we make a breaking API change, we'll bump the version appropriately. +(See Rust upstream documentation for the precise details.) + +However, many of our crates have optional unstable APIs, +enabled by cargo features. +Those features are *not* covered by semver. +When you enable those features, `cargo update` might break for you. +This will be mentioned in the documentation for the feature(s), +in each crate's `README`. + +## Unstable Tor crates + +For all `tor-*` and `arti-*` crates with 0.x version numbers: + +We will do a minor version bump (0.x -> 0.y; y > x) for all crates, +on every release (ie, roughly monthly). + +So we do not *track* semver API changes. + +We will try to retain compatibility APIs (usually for 12 months at least), +and generally try to make it easy for out-of-tree users of these crates +to do a semver upgrade - +ie, to try to make their source code changes reasonably easy. +(This is a goal, not a well-defined hard requirement.) + +When we consider that particular crates' APIs have become +sufficiently solid and future-proof, +we may switch those crates to 1.x versions. +But we do not (as of March 2024) intend to put significant effort into making this true. + +## Stable crates (1.x, 2.x, ...) and published utility crates (neither `tor-*` nor `arti-*`) + +We will do semver analysis: +we track in-tree when we breaking API changes, +and try to bump the version numbers only then. + +Crates in this category do not (non-experimentally) +export any types from unstable Tor crates, obviously. + +Crates in this category +may have more cautious MSRV policies than Arti as a whole. + +These crates might depend on `tor-*` crates internally, +but this is probably undesirable; +it's only acceptable if the utility crate has a no less firm semver policy than Arti itself. + +## User feedback and revising the policy + +We encourage downstreams to give us feedback, including +on our approach to compatibility and versioning. + +This policy is a living document; if our practices are causing trouble we will change them. diff --git a/doc/dev/Release.md b/doc/dev/Release.md index 134a67cf9..1665cff67 100644 --- a/doc/dev/Release.md +++ b/doc/dev/Release.md @@ -114,9 +114,11 @@ release?" above. Add an acknowledgement for the current sponsor(s). -4. Determine what crates have semver changes. +4. Determine what semver/version update to do to each crate. We need to sort our crates into the following tiers. + * Unstable (0.x) `tor-*` and `arti-*` crates. + (Bump minor version, to the same value for each crate.) * No changes were made. (No version bump needed) * Only non-functional changes were made. @@ -128,6 +130,13 @@ release?" above. * APIs were broken. (Bump minor if major == 0; else bump major.) + For all `tor-*` and `arti-*` crates with 0.x version numbers + (which, as of March 2024 includes all `tor-*` crates, + and all `arti-*` crates apart from `arti` itself), + we always bump the minor version and release, + even if there have been no changes. + For other crates, things are more complicated: + You can identify crates that have no changes using `maint/changed_crates`: ``` maint/changed_crates -v "arti-v$LAST_VERSION" 2>&1 >/dev/null | grep -i "no change" @@ -170,17 +179,38 @@ before you continue! 2. Increase all appropriate version numbers. - To do this, run for each crate with functional changes: - `cargo set-version --bump {patch|minor|major} -p ${CRATE}`. + For unstable (0.x) `tor-*` and `arti-*` crates, + determine the new minor number. + `maint/crate_versions | grep -P '^tor|^arti'` + will show you the existing versions, + which should usually all be the same. + Pick the next minor version, and, for each such crate: + `cargo set-version -p ${CRATE} 0.${MINOR}.0`. + + For other crates: + + * For each crate with functional changes: + `cargo set-version --bump {patch|minor|major} -p ${CRATE}`. + + * For crates with non-functional changes, + you can use the `bump_nodep` script: + `./maint/bump_nodep crate1 crate2 crate3` ... - For crates with non-functional changes, - you can use the `bump_nodep` script: - `./maint/bump_nodep crate1 crate2 crate3` ... + In all cases, make sure you commit `Cargo.lock` changes too. 3. Check for side effects from bumping versions! - Is there a Cargo.lock change you forgot to commit? - If so, commit it. + As of March 2024, you can skip this section + for `tor-*` and `arti-*`, since: + * `arti` is the only non-0.x `arti-*` or `tor-*` crate; + * `arti` does not expose types from our lower-layer crates; + * None other of our crates depend on `tor-*` or `arti-*` crates. + Therefore all necessary bumps have been done. + + You may need to perform these checks + if there have been semver bumps + to non-`arti-*` or `tor-*` crates, + when other such crates expose their types. Does a previously unchanged crate depend on a crate that got a version bump? |