doc: update PUBLISHING.md

Author: phip1611

PUBLISHING.md

@@ -5,71 +5,69 @@ 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
+## TL;DR
+- Each release should match the [`CHANGELOG.md`].
+  The changelog needs to be up-to-date before any release.
+- Each release should have a git tag like `uefi-raw-v0.4.0` or `uefi-v0.25.0`.
+- Each release should contain something useful. If we just bump `uefi` in
+  `uefi-services`, there is no real value-add (as long as the new version is
+  covered by the existing dependency version range).
 
-For ensuring compatibility within the crates ecosystem,
-Cargo [recommends][cargo-semver] maintainers to follow the [semantic versioning][semver] guidelines.
+## Semantic Versioning and Breaking Changes
 
-This means that before publishing the changes, we need to decide
-which crates were modified and how should their version numbers be incremented.
+For ensuring compatibility within the crates ecosystem,
+Cargo [recommends][cargo-semver] maintainers to follow the [semantic versioning][semver]
+guidelines of Cargo.
 
-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).
+***Note** that `0.x` -> `0.(x+1)` is allowed to be a breaking change by Cargo.*
 
-### Crate dependencies
+### Crate Dependencies & Publishing Order
 
 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.
-
-### 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.
+- `uefi` depends on `uefi-macros` and `uefi-raw`
 
-For example, if `uefi-macros` gets bumped from `1.1.0` to `2.0.0`,
-you will also have to update the corresponding `Cargo.toml` of `uefi` to be:
-
-```toml
-uefi-macros = "2.0.0"
-```
-
-The dependencies in `template/Cargo.toml` should also be updated to the new version.
+The crates need to be published in their respective natural dependency order.
+The resulting dependency bumps need to be committed.
 
 [cargo-semver]: https://doc.rust-lang.org/cargo/reference/semver.html
 [semver]: https://semver.org/
 
-## Publishing new versions of the crates
-
-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.
+## Publishing
+
+*Make sure to be familiar with the [general publishing principals][cargo-publishing-reference]
+for crates.io.*
+
+Each release should have a git tag like `uefi-raw-v0.4.0` or `uefi-v0.25.0` and
+contain something useful. If we just bump `uefi` in `uefi-services`, there is no
+real value-add (as long as the new version is covered by the existing
+dependency version range).
+
+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, and performs a release commit. If you prefer another approach, create
+the tags manually so that it matches the existing git tags in the git history.
+
+*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 as <https://github.com/rust-osdev/uefi-rs/issues/955>
+   to note 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`
+   `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 and release them.
+   Go back to `4.` for that.
+8. Search the repository for outdated versions, such as in `template/Cargo.toml`
+   and `book/src/tutorial/app.md`. 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.
 
-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
-```
 
 [cargo-publishing-reference]: https://doc.rust-lang.org/cargo/reference/publishing.html
-
-## Updating the changelog
-
-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.