diff --git a/contrib/how_to_release.md b/contrib/how_to_release.md index e4afaf4d..8b84be80 100644 --- a/contrib/how_to_release.md +++ b/contrib/how_to_release.md @@ -2,16 +2,45 @@ ## General -* When releasing a pre-release version, make sure other crates are updated to - depend on it, with an exact version requirement (`=x.y.z-tag`) -* When releasing a regular version, make sure other crates are updated to depend - on it, with a regular (same as caret / `^`) version requirement (`x.y.z`) -* Macro crates are versioned identically to their "parent" crate and are exempt - from the rule above: Dependencies from the parent crate to the macro crate - (for re-exporting) should always use exact version requirements. Whenever a - crate with an associated macro crate should get a new release, release a new - version of the macro crate with the same number first, even if there were no - changes in the macro code. +* `ruma-identifiers-validation` and the `-macros` crates don't get their own + release commit or tag since they are internal packages. +* Macro crates are versioned identically to their "parent" crate and need to be + released before the parent crate. +* `ruma-identifiers-validation` is released before `ruma-identifiers-macros` + and `ruma-identifiers`. + +## Creating a release commit + +*To be automated in the future, see https://github.com/ruma/ruma/issues/452.* + +Update `Cargo.toml` of the relevant package, and update the dependency on this +package in other crates in the workspace (if applicable): + +* When doing a prerelease (e.g. `0.10.0-beta.1`), depend on it with an exact + version requirement (`version = "=0.10.0-beta.1`) + * Macro crate dependencies always use an exact version requirement, even for + final releases. + * Otherwise, use `version = "x.y.z"`. + +Update the `CHANGELOG.md` of the relevant package. + +* If there is already a section for the version to be released, remove the + `(unreleased)` from its title. + * Otherwise, change the `[unreleased]` section title to the version being + released. + +Finally, commit these changes as `Release {crate} {version}`. + +## Publishing to crates.io and creating a release tag + +*Note: only do this for final release, i.e. not alpha or beta releases, and not +for `ruma-identifiers-validation` or one of the macro crates.* + +All you have to do is run the corresponding `xtask` command: + +``` +cargo xtask release {crate} +``` ## Dependencies