Update PUBLISHING.md for auto-release workflow

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,58 +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`.
+- `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