Skip to content

Commit

Permalink
Auto merge of rust-lang#12745 - epage:publish, r=weihanglo
Browse files Browse the repository at this point in the history
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.

The list of tools included was based on a mixture of
- Download counts
- Word of mouth exposure
- Unique aspects covered
- Maturity

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
bors committed Sep 27, 2023
2 parents e6aabe8 + d06fd70 commit 01846d9
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 01846d9

Please sign in to comment.