@@ -5,71 +5,69 @@ the crates in this repository to [crates.io](https://crates.io/).
55
66** It is mostly intended for maintainers of the uefi-rs project.**
77
8- ## Bumping the crate versions
8+ ## TL;DR
9+ - Each release should match the [ ` CHANGELOG.md ` ] .
10+ The changelog needs to be up-to-date before any release.
11+ - Each release should have a git tag like ` uefi-raw-v0.4.0 ` or ` uefi-v0.25.0 ` .
12+ - Each release should contain something useful. If we just bump ` uefi ` in
13+ ` uefi-services ` , there is no real value-add (as long as the new version is
14+ covered by the existing dependency version range).
915
10- For ensuring compatibility within the crates ecosystem,
11- Cargo [ recommends] [ cargo-semver ] maintainers to follow the [ semantic versioning] [ semver ] guidelines.
16+ ## Semantic Versioning and Breaking Changes
1217
13- This means that before publishing the changes, we need to decide
14- which crates were modified and how should their version numbers be incremented.
18+ For ensuring compatibility within the crates ecosystem,
19+ Cargo [ recommends] [ cargo-semver ] maintainers to follow the [ semantic versioning] [ semver ]
20+ guidelines of Cargo.
1521
16- Incrementing the version number of a crate is as simple as editing
17- the corresponding ` Cargo.toml ` file and updating the ` version = ... ` line,
18- then committing the change (preferably on a new branch, so that all the version bumps
19- can be combined in a single pull request).
22+ *** Note** that ` 0.x ` -> ` 0.(x+1) ` is allowed to be a breaking change by Cargo.*
2023
21- ### Crate dependencies
24+ ### Crate Dependencies & Publishing Order
2225
2326The dependency graph of the published crates in this repo is:
2427
2528- ` uefi-services ` depends on ` uefi ` (the root project)
26- - ` uefi ` depends on ` uefi-macros `
27- 28- If there are breaking changes happening in the project, we should first publish
29- a new version of ` uefi-macros ` , then of ` uefi ` , then of ` uefi-services ` and so on.
30- 31- For example, if the signature of a widely-used macro from ` uefi-macros ` is changed,
32- a new major version of that crate will have to be published, then a new version of
33- ` uefi ` (major if the previous bump caused changes in the public API of this crate as well),
34- then possibly a new version of ` uefi-services ` .
35- 36- Furthermore, ` uefi-macros ` has the ` uefi ` crate as a ` dev-dependency ` ,
37- and that will have to be updated in tandem with the major versions of the core crate.
38- 39- ### Updating the dependent crates
40- 41- Remember that if a new major version of a crate gets released, when bumping the version
42- of it's dependents you will have to also change the dependency line for it.
29+ - ` uefi ` depends on ` uefi-macros ` and ` uefi-raw `
4330
44- For example, if ` uefi-macros ` gets bumped from ` 1.1.0 ` to ` 2.0.0 ` ,
45- you will also have to update the corresponding ` Cargo.toml ` of ` uefi ` to be:
46- 47- ``` toml
48- uefi-macros = " 2.0.0"
49- ```
50- 51- The dependencies in ` template/Cargo.toml ` should also be updated to the new version.
31+ The crates need to be published in their respective natural dependency order.
32+ The resulting dependency bumps need to be committed.
5233
5334[ cargo-semver ] : https://doc.rust-lang.org/cargo/reference/semver.html
5435[ semver ] : https://semver.org/
5536
56- ## Publishing new versions of the crates
57- 58- This section is mostly a summary of the official [ guide to publishing on crates.io] [ cargo-publishing-reference ] ,
59- with a few remarks regarding the specific of this project.
37+ ## Publishing
38+ 39+ * Make sure to be familiar with the [ general publishing principals] [ cargo-publishing-reference ]
40+ for crates.io.*
41+ 42+ Each release should have a git tag like ` uefi-raw-v0.4.0 ` or ` uefi-v0.25.0 ` and
43+ contain something useful. If we just bump ` uefi ` in ` uefi-services ` , there is no
44+ real value-add (as long as the new version is covered by the existing
45+ dependency version range).
46+ 47+ To simplify things, you can use the [ ` cargo-release ` ] ( https://crates.io/crates/cargo-release )
48+ utility, which automatically bumps crate versions in ` Cargo.toml ` , creates
49+ git tags, and performs a release commit. If you prefer another approach, create
50+ the tags manually so that it matches the existing git tags in the git history.
51+ 52+ * The following guide assumes that you are using ` cargo-release ` .*
53+ 54+ 1 . Make sure that the ` main ` branch passes CI. Also verify that locally by
55+ running ` cargo xtask test && cargo xtask run ` .
56+ 2 . Create an issue similar as < https://github.com/rust-osdev/uefi-rs/issues/955 >
57+ to note what you want to release.
58+ 3 . Make sure that the [ ` CHANGELOG.md ` ] is up-to-date and matches the format.
59+ 4 . Perform a dry run: ` cargo release -p uefi-raw 0.4.0 `
60+ ` cargo-release ` will automatically increase the version number for you, if
61+ it is still lower.
62+ 5 . Release: ` cargo release -p uefi-raw 0.4.0 --execute `
63+ 6 . Update the lock file: ` cargo xtask build `
64+ 7 . If necessary: Bump the dependency in the dependent crates, commit this, and
65+ if applicable release them. Go back to ` 4. ` for that.
66+ 8 . Search the repository for outdated versions, such as in ` template/Cargo.toml `
67+ and ` book/src/tutorial/app.md ` . Run ` cargo xtask build ` again and update +
68+ commit the lock file, if there are changes.
69+ 9 . Submit a PR. Make sure to push all tags using ` git push --tags ` .
70+ 10 . Update this document, in case something is inconvenient or unclear.
6071
61- Start by following the steps in the guide. When running ` cargo publish ` ,
62- you will have to use a custom ` --target ` flag to be able to build/verify the crates:
63- 64- ```
65- cargo publish --target x86_64-unknown-uefi
66- ```
6772
6873[ cargo-publishing-reference ] : https://doc.rust-lang.org/cargo/reference/publishing.html
69- 70- ## Updating the changelog
71- 72- After bumping the crate versions, we should also update the [ ` CHANGELOG.md ` ] ( CHANGELOG.md ) file
73- in order to move all the unpublished changes to their respective version, and prepare it for
74- tracking further changes. The date of the release should be included next to the section title as
75- done for the other releases.
0 commit comments