Versioning and releases
beave-rs is published on crates.io as the beavers crate. Releases follow
Semantic Versioning as Cargo interprets it.
Version numbers
While the major version is 0, the minor version is the breaking-change
number:
| Change | Before 1.0 | From 1.0 |
|---|---|---|
| Breaking change | 0.x.y → 0.(x+1).0 |
x.y.z → (x+1).0.0 |
| Backward-compatible addition | 0.x.y → 0.x.(y+1) |
x.y.z → x.(y+1).0 |
| Bug fix | 0.x.y → 0.x.(y+1) |
x.y.z → x.y.(z+1) |
A dependency requirement of beavers = "0.1" therefore never picks up a
breaking change.
Version 0.0.1 is a placeholder published only to reserve the crate name on
crates.io. Later 0.0.x versions are previews for trying the API and may break
anything in every release. Cargo treats every 0.0.x version as incompatible
with every other, so applications should wait for 0.1.0, the first release
intended for use.
Pre-release versions such as 0.2.0-rc.1 may be published to let applications
try a breaking release before it becomes the default.
Compatibility contract
Beyond Rust signatures, the following are part of the compatibility contract and change only in a breaking release:
- Public items reachable from the crate root, including trait methods, public fields, enum variants, and the bounds on generic parameters.
- Cargo feature names and the items each feature enables.
- Delivery behavior that applications rely on: when a delivery is acknowledged, retried, routed to a dead-letter destination, or stops its subscription.
- Data visible outside the process: header and property names written by the adapters, dead-letter metadata, trace-context propagation fields, metric names and labels, span names and fields, and the health endpoint paths.
- Types and traits of dependencies that appear in the public API: the
apache-avrocrate'sAvroSchemaandSchemawith theavrofeature, and theprostcrate'sMessagewith theprotobuffeature. Upgrading such a dependency to a semver-incompatible version is a breaking change forbeavers. Broker client crates, such asrdkafka, do not appear in the public API.
Enums and structs marked #[non_exhaustive], such as FailureKind,
RetryPolicy, and the adapters' *Metadata structs, may gain variants and
fields in a backward-compatible release. Match them with a wildcard arm, and
build them from their constructors or Default and setter methods.
Fixing behavior that contradicts the documented contract is a bug fix, even when an application could observe the difference.
Minimum supported Rust version
The minimum supported Rust version (MSRV) is declared as rust-version in
Cargo.toml and checked in CI with every Cargo feature enabled. Raising it is
allowed in a minor release before 1.0 and is called out in the release notes.
The MSRV is not raised merely to adopt newer language features; it follows the
requirements of the broker client dependencies.
Changelog
CHANGELOG.md follows Keep a Changelog.
Every pull request that changes behavior visible to applications adds an entry
under Unreleased, in the Added, Changed, Deprecated, Removed, Fixed,
or Security section. Breaking changes are marked with Breaking and say
what applications must change.
Release procedure
- Choose the version from the changes under
Unreleasedand the table above. - Rename
UnreleasedinCHANGELOG.mdto the version and release date, and start a new emptyUnreleasedsection. - Set
versioninCargo.tomland runcargo checkto updateCargo.lock. - Merge these changes to
mainand wait for CI, including the package check. - Run the
Releaseworkflow onmainfrom the Actions tab. It refuses a version that already has a tag or is already on crates.io, runscargo publish, tags the commit asvX.Y.Z, and creates a GitHub release whose notes are the version's changelog section.
The workflow publishes with the CARGO_REGISTRY_TOKEN secret, a crates.io API
token with the publish-new and publish-update scopes, limited to the
beavers crate once it exists and given an expiry date. Store it as a secret of
the crates-io environment, restrict that environment's deployment branches to
main, and add required reviewers so that each release waits for approval.
Pull requests from forks never receive the secret. The release job does not
restore build caches, so a cache written by another workflow cannot affect the
published crate.
A published version cannot be replaced. If a release is broken, yank it with
cargo yank --version X.Y.Z and publish a fixed patch release.
Project website
The website has a landing page and the guides, built by
tools/pages/build.mjs with one header and one stylesheet,
tools/pages/style.css. The landing page body is hand-written HTML in
site/index.html; its links are relative to the site root. Each
docs/<path>.md becomes docs/<path>.html with a navigation sidebar, and a
README.md inside docs/ becomes index.html in its directory. Code blocks on
both are highlighted at build time.
Each guide's Markdown source is published at the same path with .md instead
of .html, so replacing the extension in a guide URL returns the exact source.
The landing page's Markdown, index.md, is the repository README. Links
between guides point at the generated pages; links to other repository files
point at GitHub, in both the HTML and the Markdown copies. The navigation lists the guide index, then one group per ## section of
docs/README.md, with the guides in that section's link order.
For language-model tools, the site root also serves llms.txt, which lists the
Markdown URL of every page, and llms-full.txt, which holds all pages in one
file.
The Pages workflow runs the build and publishes the result to the gh-pages
branch on every push to main that touches site/, README.md, docs/, or
tools/pages/. GitHub Pages serves that branch, so the repository's Pages
source must be set to deploy from the gh-pages branch root.
A pull request that changes the website gets a preview under
pr-preview/pr-<number>/ on the same branch. The workflow comments the preview
URL on the pull request and removes the preview when the pull request closes.
Pull requests from forks are not previewed because their workflows cannot push
to the repository.
Build and preview the site locally with Node.js 22:
npm ci --prefix tools/pages
node tools/pages/build.mjs _site
python3 -m http.server -d _site
The character artwork slot in the landing page is a placeholder; replace the
character figure in site/index.html with the artwork when it exists.