diff --git a/PUBLISHING.md b/PUBLISHING.md index ae3959a90..19458cc35 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -1,11 +1,21 @@ # Publishing new versions of uefi-rs to Crates.io -This guide documents the best practices for publishing new versions of -the crates in this repository to [crates.io](https://crates.io/). +This guide documents how to publish new versions of the crates in this +repository to [crates.io](https://crates.io/). **It is mostly intended for maintainers of the uefi-rs project.** -## Bumping the crate versions +## Overview + +1. Create a branch that updates the versions of all packages you want to + release. This branch should include all related changes such as updating the + versions in dependent crates and updating the changelog. +2. Create a PR of that branch. The subject of the PR must start with `release:`, + the rest of the message is arbitrary. +3. Once the PR is approved and merged, a Github Actions workflow will take care + of creating git tags and publishing to crates.io. + +## Details of the release pull request For ensuring compatibility within the crates ecosystem, Cargo [recommends][cargo-semver] maintainers to follow the [semantic versioning][semver] guidelines. @@ -15,61 +25,46 @@ which crates were modified and how should their version numbers be incremented. Incrementing the version number of a crate is as simple as editing the corresponding `Cargo.toml` file and updating the `version = ...` line, -then committing the change (preferably on a new branch, so that all the version bumps -can be combined in a single pull request). +then committing the change. ### Crate dependencies The dependency graph of the published crates in this repo is: -- `uefi-services` depends on `uefi` (the root project) -- `uefi` depends on `uefi-macros` - -If there are breaking changes happening in the project, we should first publish -a new version of `uefi-macros`, then of `uefi`, then of `uefi-services` and so on. - -For example, if the signature of a widely-used macro from `uefi-macros` is changed, -a new major version of that crate will have to be published, then a new version of -`uefi` (major if the previous bump caused changes in the public API of this crate as well), -then possibly a new version of `uefi-services`. - -Furthermore, `uefi-macros` has the `uefi` crate as a `dev-dependency`, -and that will have to be updated in tandem with the major versions of the core crate. +- `uefi-services` depends on `uefi` +- `uefi` depends on `uefi-macros` and `uefi-raw` ### Updating the dependent crates Remember that if a new major version of a crate gets released, when bumping the version of it's dependents you will have to also change the dependency line for it. -For example, if `uefi-macros` gets bumped from `1.1.0` to `2.0.0`, +For example, if `uefi-macros` gets bumped from `0.5.0` to `0.6.0`, you will also have to update the corresponding `Cargo.toml` of `uefi` to be: ```toml -uefi-macros = "2.0.0" +uefi-macros = "0.6.0" ``` -The dependencies in `template/Cargo.toml` should also be updated to the new version. +The dependencies in `template/Cargo.toml` and `book/src/tutorial/app.md` should +also be updated to the new version. [cargo-semver]: https://doc.rust-lang.org/cargo/reference/semver.html [semver]: https://semver.org/ -## Publishing new versions of the crates +### Updating the changelog -This section is mostly a summary of the official [guide to publishing on crates.io][cargo-publishing-reference], -with a few remarks regarding the specific of this project. - -Start by following the steps in the guide. When running `cargo publish`, -you will have to use a custom `--target` flag to be able to build/verify the crates: - -``` -cargo publish --target x86_64-unknown-uefi -``` +Update the [`CHANGELOG.md`](CHANGELOG.md) file in order to move all the +unpublished changes to their respective version, and prepare it for tracking +further changes. The date of the release should be included next to the section +title as done for the other releases. -[cargo-publishing-reference]: https://doc.rust-lang.org/cargo/reference/publishing.html +## Crates.io secret token -## Updating the changelog +The release.yml workflow expects a repository secret named +`CARGO_REGISTRY_TOKEN`. This is set in the [repository settings][secret]. The +value must be a crates.io [API token]. The scope of the token should be +restricted to `publish-update`. -After bumping the crate versions, we should also update the [`CHANGELOG.md`](CHANGELOG.md) file -in order to move all the unpublished changes to their respective version, and prepare it for -tracking further changes. The date of the release should be included next to the section title as -done for the other releases. +[secret]: https://github.com/rust-osdev/uefi-rs/settings/secrets/actions +[API token]: https://crates.io/settings/tokens