Skip to content

Latest commit

 

History

History
90 lines (66 loc) · 3.89 KB

PUBLISHING.md

File metadata and controls

90 lines (66 loc) · 3.89 KB
Raw

Publishing new versions of uefi-rs to Crates.io

This guide documents how to publish new versions of the crates in this repository to crates.io.

It is mostly intended for maintainers of the uefi-rs project.

Goal: What We Want

  • We want precise entries in the CHANGELOG.md for every release that follow our existing format. Changes are supposed to be added before a release is performed.
  • We want git tags like uefi-raw-v0.4.0 or uefi-v0.25.0 for every release.
  • We want our crate dependencies published in the right order (if necessary):
    • uefi depends on uefi-macros and uefi-raw

How: Ways to Publish

There are two major ways for releasing/publishing.

GitHub CI Workflow (recommended)

  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. Example
  3. Once the PR is approved and merged, a GitHub Actions workflow will take care of creating git tags and publishing to crates.io.

Crates.io secret token

The release.yml workflow expects a repository secret named CARGO_REGISTRY_TOKEN. This is set in the repository settings. The value must be a crates.io API token. The scope of the token should be restricted to publish-update.

Manual

To simplify things, you can use the cargo-release utility, which automatically bumps crate versions in Cargo.toml, creates git tags as we want them, and creates a release commit. If you prefer a more manual process, create the tags manually so that it matches the existing git tag scheme.

The following guide assumes that you are using cargo-release.

  1. Make sure that the main branch passes CI. Also verify that locally by running cargo xtask test && cargo xtask run.
  2. Create an issue similar to #955 for noting what you want to release.
  3. Make sure that the CHANGELOG.md is up-to-date and matches the format.
  4. Perform a dry run: cargo release -p uefi-raw 0.4.0 Hint: cargo-release will automatically increase the version number for you, if it is still lower.
  5. Release: cargo release -p uefi-raw 0.4.0 --execute
  6. Update the lock file: cargo xtask build
  7. If necessary: Bump the dependency in the dependent crates, commit this, and if applicable release them. Go back to 4. for that.
  8. Search the repository for outdated versions, such as in template/Cargo.toml. Run cargo xtask build again and update + commit the lock file, if there are changes.
  9. Submit a PR. Make sure to push all tags using git push --tags.
  10. Update this document, in case something is inconvenient or unclear.

General Guidelines and Tips

Publishing Principals for crates.io

Make sure to be familiar with the general publishing principals for crates.io.

Details of the release pull request

For ensuring compatibility within the crates ecosystem, Cargo recommends maintainers to follow the semantic versioning guidelines.

This means that before publishing the changes, we need to decide which crates were modified and how should their version numbers be incremented.

Note that 0.x -> 0.(x+1) is allowed to be a breaking change by Cargo.