doc: update PUBLISHING.md

PUBLISHING.md

@@ -5,65 +5,87 @@ repository to [crates.io](https://crates.io/).
 
 **It is mostly intended for maintainers of the uefi-rs project.**
 
-## Overview
+## 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-services` depends on `uefi`
+  - `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.
-3. Once the PR is approved and merged, a Github Actions workflow will take care
+   the rest of the message is arbitrary. [Example](https://github.com/rust-osdev/uefi-rs/pull/1001)
+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
+#### Crates.io secret token
 
-For ensuring compatibility within the crates ecosystem,
-Cargo [recommends][cargo-semver] maintainers to follow the [semantic versioning][semver] guidelines.
-
-This means that before publishing the changes, we need to decide
-which crates were modified and how should their version numbers be incremented.
+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`.
 
-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.
+[secret]: https://github.com/rust-osdev/uefi-rs/settings/secrets/actions
+[API token]: https://crates.io/settings/tokens
 
-### Crate dependencies
+### Manual
 
-The dependency graph of the published crates in this repo is:
+To simplify things, you can use the [`cargo-release`](https://crates.io/crates/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.
 
-- `uefi-services` depends on `uefi`
-- `uefi` depends on `uefi-macros` and `uefi-raw`
+*The following guide assumes that you are using `cargo-release`.*
 
-### Updating the dependent crates
+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 <https://github.com/rust-osdev/uefi-rs/issues/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.
 
-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.
+## General Guidelines and Tips
 
-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:
+### Publishing Principals for crates.io
 
-```toml
-uefi-macros = "0.6.0"
-```
+Make sure to be familiar with the [general publishing principals][cargo-publishing-reference]
+for [crates.io](https://crates.io).
 
-The dependencies in `template/Cargo.toml` should also be updated to the new version.
+[cargo-publishing-reference]: https://doc.rust-lang.org/cargo/reference/publishing.html
 
-[cargo-semver]: https://doc.rust-lang.org/cargo/reference/semver.html
-[semver]: https://semver.org/
+### Details of the release pull request
 
-### Updating the changelog
+For ensuring compatibility within the crates ecosystem,
+Cargo [recommends][cargo-semver] maintainers to follow the [semantic versioning][semver] guidelines.
 
-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.
+This means that before publishing the changes, we need to decide
+which crates were modified and how should their version numbers be incremented.
 
-## Crates.io secret token
+***Note** that `0.x` -> `0.(x+1)` is allowed to be a breaking change by Cargo.*
 
-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`.
+[cargo-semver]: https://doc.rust-lang.org/cargo/reference/semver.html
+[semver]: https://semver.org/
 
-[secret]: https://github.com/rust-osdev/uefi-rs/settings/secrets/actions
-[API token]: https://crates.io/settings/tokens
+[`CHANGELOG.md`]: CHANGELOG.md