How to release a beta version of a crate for limited public testing?

Question

I want to carefully release a new version of a crate to give users a chance to test it first. How can I release it to crates.io as a "beta"? (similar to how npm has @next tagged releases).

It's not supposed to be a breaking change, so I'm not going to increase semver-major version. I don't want it to be automatically picked when users do cargo upgrade until the beta testing period ends.

• What version syntax should I use for the release?

• Do I need to use any special cargo options when releasing it?

• How do users use cargo/Cargo.toml to opt in into the beta version?

Answer 1

Semantic versioning defines the concept of a pre-release version:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92

To use this in Cargo, publish a crate of the planned version number but append a pre-release identifier. I suggest -beta.0, allowing you to easily increase if you need a second:

[package]
name = "library"
version = "0.1.1-beta.0"

To use this, you need to specifically opt into it by putting beta into the version requirement:

[dependencies]
library = "0.1.1-beta"

---

To test this, I:

1. Spun up a local crates.io server
2. Uploaded the crate library with version 0.1.0
3. Used library = "0.1.0" in a binary project app — it resolved to 0.1.0
4. Uploaded the crate library with version 0.1.1-beta.0
5. Ran cargo update in app — the version did not change.
6. Changed to library = "0.1.1-beta" in app, ran cargo update — the version did change.
7. Uploaded the crate library with version 0.1.1-beta.1
8. Ran cargo update in app — the version did change.