Skip to content

Commit d8172e9

Browse files
committed
docs(ref): Establish publish best practices
Inspired by rust-lang#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.
1 parent 25dc3bd commit d8172e9

File tree

1 file changed

+13
-0
lines changed

1 file changed

+13
-0
lines changed

src/doc/src/reference/publishing.md

+13
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,19 @@ In order to release a new version, change [the `version` value](manifest.md#the-
136136
Keep in mind [the SemVer rules](semver.md) which provide guidelines on what is a compatible change.
137137
Then run [`cargo publish`] as described above to upload the new version.
138138

139+
> **Recommendation:** Consider the full release process and automate what you can.
140+
>
141+
> Each version should include:
142+
> - A changelog entry, preferrably [manually curated](https://keepachangelog.com/en/1.0.0/) though a generated one is better than nothing
143+
> - A [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) pointing to the published commit
144+
>
145+
> Examples of third-party tools that are representative of different workflows include (in alphabetical order):
146+
> - [cargo-release](https://crates.io/crates/cargo-release)
147+
> - [cargo-smart-release](https://crates.io/crates/cargo-smart-release)
148+
> - [release-plz](https://crates.io/crates/release-plz)
149+
>
150+
> For more, see [crates.io](https://crates.io/search?q=cargo%20release)
151+
139152
## Managing a crates.io-based crate
140153

141154
Management of crates is primarily done through the command line `cargo` tool

0 commit comments

Comments
 (0)