From d06fd706e5bd121519b89043e4c380a67ff04b30 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 26 Sep 2023 13:28:51 -0500 Subject: [PATCH] docs(ref): Establish publish best practices Inspired by #841 and conversations at RustConf. At RustConf, someone was talking to me about the lack or inconsistent use of best practices within the crate ecosystem. We have a challenge of needing to help users get up and going who can't research every last decision while not over-encouraging the status quo, leading to stagnation. I do have a bias in this conversation as the maintainer of one of these tools which is why I decided to pick an ordering without judgement. I picked alphabetical ordering before sorting and realizing this puts my own crate first. --- src/doc/src/reference/publishing.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md index 959153cd7a7..54a8635fbf2 100644 --- a/src/doc/src/reference/publishing.md +++ b/src/doc/src/reference/publishing.md @@ -136,6 +136,19 @@ In order to release a new version, change [the `version` value](manifest.md#the- Keep in mind [the SemVer rules](semver.md) which provide guidelines on what is a compatible change. Then run [`cargo publish`] as described above to upload the new version. +> **Recommendation:** Consider the full release process and automate what you can. +> +> Each version should include: +> - A changelog entry, preferrably [manually curated](https://keepachangelog.com/en/1.0.0/) though a generated one is better than nothing +> - A [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) pointing to the published commit +> +> Examples of third-party tools that are representative of different workflows include (in alphabetical order): +> - [cargo-release](https://crates.io/crates/cargo-release) +> - [cargo-smart-release](https://crates.io/crates/cargo-smart-release) +> - [release-plz](https://crates.io/crates/release-plz) +> +> For more, see [crates.io](https://crates.io/search?q=cargo%20release). + ## Managing a crates.io-based crate Management of crates is primarily done through the command line `cargo` tool