release_utils/
lib.rs

1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! Utilities for automatically releasing Rust code.
10//!
11//! The intended usage is something like this (but not necessarily exactly
12//! this):
13//!
14//! 1. All code changes needed for a release are made by a developer in a
15//!    regular git commit. The commit includes bumping the version in
16//!    `Cargo.toml`, and any updates to `Cargo.lock`, changelog files, etc.
17//! 2. The commit message is prefixed with `release:` to mark the commit as
18//!    a release trigger.
19//! 3. The commit is reviewed and merged through the normal pull request
20//!    process.
21//! 4. Once merged, an automatic job sees the specially-marked commit and
22//!    triggers any actions necessary to push the release. The building
23//!    blocks for this automated part are what `release-utils-rs` provides.
24//!
25//! # Example code for a release job
26//!
27//! ```
28//! use release_utils::release::*;
29//! use release_utils::{get_github_sha, Package, Repo};
30//! use std::error::Error;
31//!
32//! /// Entry point for the auto-release process. This is intended to be run
33//! /// from a Github Actions workflow.
34//! fn auto_release() -> Result<(), Box<dyn Error>> {
35//!     let commit_sha = get_github_sha()?;
36//!     let repo = Repo::open()?;
37//!     let commit_message_subject =
38//!         repo.get_commit_message_subject(&commit_sha)?;
39//!
40//!     if !commit_message_subject.starts_with("release:") {
41//!         println!("{commit_sha} does not contain the release trigger");
42//!         return Ok(());
43//!     }
44//!
45//!     Ok(release_packages(&[
46//!         Package::new("foo"),
47//!         Package::new("bar"),
48//!     ])?)
49//! }
50//! ```
51//!
52//! # Example Github Actions workflow
53//!
54//! ```toml
55//! on:
56//!   push:
57//!     branches:
58//!       - main
59//!
60//! name: Release
61//!
62//! permissions:
63//!   contents: write
64//!
65//! jobs:
66//!   release:
67//!     runs-on: ubuntu-latest
68//!     steps:
69//!       - uses: actions/checkout@v4
70//!       - run: cargo xtask release
71//!         env:
72//!           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
73//! ```
74//!
75//! # Cargo registry token
76//!
77//! The above Github Actions workflow requires a secret token. Generate
78//! the token in your crates.io [Account Settings]. The token scopes
79//! must include `publish-update`. If the crate has never been published
80//! before, `publish-new` is also required.
81//!
82//! To make the token available to the Github Actions workflow:
83//! 1. Go to your repository's settings
84//! 2. Click to `Secrets and variables` in the sidebar, then click `Actions`
85//! 3. Under `Repository secrets`, click `New repository secret`.
86//!
87//! [Account Settings]: https://crates.io/settings/tokens
88
89#![deny(unsafe_code)]
90#![warn(missing_docs)]
91
92mod crate_registry;
93mod env;
94mod git;
95mod package;
96
97pub mod cmd;
98pub mod github;
99pub mod release;
100
101pub use crate_registry::{CrateRegistry, GetCrateVersionsError};
102pub use env::{get_github_sha, VarError};
103pub use git::{Repo, RepoOpenError};
104pub use package::{GetLocalVersionError, Package};
release_utils/lib.rs

release_utils/
lib.rs
