Skip to content

Commit

Permalink
docs(ref): Establish publish best practices
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
epage committed Sep 26, 2023
1 parent e6aabe8 commit d06fd70
Showing 1 changed file with 13 additions and 0 deletions.
13 changes: 13 additions & 0 deletions src/doc/src/reference/publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit d06fd70

Please sign in to comment.