Write guide on releasing the CLI (#447)

BD103 · web-flow · commit 9fad68c475ba · 2025-05-20T23:16:16.000Z
This proposes a process for releasing the CLI, based it off of the linter release guide. Some noticeable points: 1. Releasing the CLI requires Bevy engine maintainer approval. - This smooths migration for when the CLI becomes an official Bevy tool, since it will become required then. 2. The Github release description looks very similar [to the linter's](https://github.com/TheBevyFlock/bevy_cli/releases/tag/lint-v0.3.0). This is good for consistency, but may be confusing and hard to tell the difference between the two. Any ideas on how to differentiate them further?
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,12 @@
+# Changelog
+
+All notable user-facing changes to the **Bevy CLI** will be documented in this file.
+
+The format is based on [Keep a Changelog], and this project adheres to [Semantic Versioning].
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
+
+## Unreleased
+
+**All Changes**: [`main`](https://github.com/TheBevyFlock/bevy_cli/commits/main)
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,13 @@
+# Migration Guide
+
+Occasionally changes are made to the **Bevy CLI** that may break existing projects, or majorly change how it is intended to be used. This document provides a guide recommending how to upgrade your existing project to a newer version of the CLI.
+
+To actually install the new version of the CLI, please see [the docs] and [the releases page]. Note that some changes listed here are optional (and will be explicitly marked as such). If you ever run into issues while upgrading, please feel free to [submit an issue].
+
+[the docs]: https://thebevyflock.github.io/bevy_cli/cli/index.html
+[the releases page]: https://github.com/TheBevyFlock/bevy_cli/releases
+[submit an issue]: https://github.com/TheBevyFlock/bevy_cli/issues
+
+> **Note**
+>
+> This document is empty for now, and will be until v0.2.0 of the CLI is released with actual breaking changes. Check back later :)
diff --git a/bevy_lint/CHANGELOG.md b/bevy_lint/CHANGELOG.md
@@ -1,17 +1,17 @@
 # Changelog
 
-All notable user-facing changes to this project will be documented in this file.
+All notable user-facing changes to the **Bevy Linter** will be documented in this file.
 
 The format is based on [Keep a Changelog], and this project adheres to [Semantic Versioning].
 
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 
-## [Unreleased]
+## Unreleased
 
 **All Changes**: [`lint-v0.3.0...main`](https://github.com/TheBevyFlock/bevy_cli/compare/lint-v0.3.0...main)
 
-## [v0.3.0] - 2025-04-30
+## v0.3.0 - 2025-04-30
 
 **All Changes**: [`lint-v0.2.0...lint-v0.3.0`](https://github.com/TheBevyFlock/bevy_cli/compare/lint-v0.2.0...lint-v0.3.0)
 
@@ -45,7 +45,7 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
     - The goal of the lint is to encourage the `AppExit` to be handled, although returning it from `main()` is just one solution. This fix prevents the lint from yelling at you if you choose to handle it a different way, or simply choose to discard it with `let _ = app.run();`.
 - Fixed the Rust version in the compatibility table for v0.2.0 ([#363](https://github.com/TheBevyFlock/bevy_cli/pull/363))
 
-## [v0.2.0] - 2025-03-19
+## v0.2.0 - 2025-03-19
 
 **All Changes**: [`lint-v0.1.0...lint-v0.2.0`](https://github.com/TheBevyFlock/bevy_cli/compare/lint-v0.1.0...lint-v0.2.0)
 
@@ -72,9 +72,9 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 - `rustc_driver.dll` not found on Windows ([#281](https://github.com/TheBevyFlock/bevy_cli/pull/281))
     - `bevy_lint` should now work on Windows, as it was previously broken by this bug.
 
-## [v0.1.0] - 2024-11-17
+## v0.1.0 - 2024-11-17
 
-**All Changes**: [`17834eb...lint-v0.1.0`](https://github.com/TheBevyFlock/bevy_cli/compare/17834eb...lint-v0.1.0)
+**All Changes**: [`lint-v0.1.0`](https://github.com/TheBevyFlock/bevy_cli/commits/lint-v0.1.0)
 
 ### Added
 
diff --git a/bevy_lint/MIGRATION.md b/bevy_lint/MIGRATION.md
@@ -1,6 +1,6 @@
 # Migration Guide
 
-Occasionally, changes are made to `bevy_lint` that may break existing projects, or majorly changes how it is intended to be used. This document provides a guide recommending how to upgrade your existing project to a newer version of the linter.
+Occasionally changes are made to the **Bevy Linter** that may break existing projects, or majorly change how it is intended to be used. This document provides a guide recommending how to upgrade your existing project to a newer version of the linter.
 
 To actually install the new version of the linter, please see [the docs] and [the releases page]. Note that some changes listed here are optional (and will be explicitly marked as such). If you ever run into issues while upgrading, please feel free to [submit an issue].
 
@@ -16,7 +16,7 @@ The linter now supports Bevy 0.16, but no longer supports Bevy 0.15. You may sti
 
 To migrate your code base to Bevy 0.16, please see the [release post][bevy 0.16 release post] and [migration guide][bevy 0.16 migration guide].
 
-[bevy 0.16 release post]: TODO
+[bevy 0.16 release post]: https://bevyengine.org/news/bevy-0-16/
 [bevy 0.16 migration guide]: https://bevyengine.org/learn/migration-guides/0-15-to-0-16/
 
 ### [Bumped Nightly Toolchain to `nightly-2025-04-03`](https://github.com/TheBevyFlock/bevy_cli/pull/278)
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -14,6 +14,8 @@
 - [Configuration](cli/configuration.md)
 - [Configuration Reference](cli/configuration/reference.md)
 - [Troubleshooting](cli/troubleshooting.md)
+- [Changelog](cli/changelog.md)
+- [Migration Guide](cli/migration.md)
 
 # Linter User Guide
 
@@ -26,11 +28,15 @@
     - [Toggling Lints in Code](linter/usage/toggling-lints-code.md)
 - [Compatibility](linter/compatibility.md)
 - [Github Actions](linter/github-actions.md)
+- [Changelog](linter/changelog.md)
+- [Migration Guide](linter/migration.md)
 
 ---
 
 # CLI Contributor's Guide
 
+- [How to Release the CLI](contribute/cli/release.md)
+
 # Linter Contributor's Guide
 
 - [About](contribute/linter/index.md)
diff --git a/docs/src/cli/changelog.md b/docs/src/cli/changelog.md
@@ -0,0 +1 @@
+{{#include ../../../CHANGELOG.md}}
diff --git a/docs/src/cli/migration.md b/docs/src/cli/migration.md
@@ -0,0 +1 @@
+{{#include ../../../MIGRATION.md}}
diff --git a/docs/src/contribute/cli/release.md b/docs/src/contribute/cli/release.md
@@ -0,0 +1,72 @@
+# How to Release the CLI
+
+## Kick-off Pull Request
+
+1. Review the changelog (`CHANGELOG.md`) and ensure that all notable changes have been documented.
+2. Replace `[Unreleased]` heading with the version with the format `[vX.Y.Z] - YYYY-MM-DD`.
+3. Update the `**All Changes**` link to compare from `main` to the new tag `cli-vX.Y.Z`. (E.g. `cli-v0.1.0...main` to `cli-v0.1.0...cli-v0.2.0`.)
+4. Review the migration guide (`MIGRATION.md`) and ensure all breaking / significant changes from the previous version are documented.
+5. Remove the `-dev` suffix from the version in `Cargo.toml`.
+    - Please ensure that `Cargo.lock` also updates!
+6. Commit your changes and open a pull request.
+7. Merge the PR once a core Bevy maintainer approves it with no outstanding issues from other contributors.
+    - This starts the release process, enacting a freeze on all other changes until the release has finished. While maintainers need to be aware of this so they do not merge PRs during this time, the release process should take less than an hour, so it's unlikely to ever be an issue.
+
+## Release on Github
+
+1. [Create a new Github release](https://github.com/TheBevyFlock/bevy_cli/releases/new).
+2. Set the tag to `cli-vX.Y.Z`.
+3. Set the title to `` `bevy_cli` - vX.Y.Z``.
+4. Paste and fill out the following template into the release documentation:
+
+````markdown
+<!-- One-sentence summary of changes. What awesome features can we spotlight? What critical bugs were fixed? -->
+
+You can find the live documentation for this release [here](https://thebevyflock.github.io/bevy_cli/cli/index.html). You may also be interested in [the changelog] and [the migration guide].
+
+<!-- Make sure to update the tags in these links to point to the correct version. -->
+
+[the changelog]: https://github.com/TheBevyFlock/bevy_cli/blob/cli-vX.Y.Z/CHANGELOG.md
+[the migration guide]: https://github.com/TheBevyFlock/bevy_cli/blob/cli-vX.Y.Z/MIGRATION.md
+
+> [!WARNING]
+>
+> This is an unofficial community project, hacked upon by the Bevy CLI working group until it is eventually upstreamed into the main [Bevy Engine organization](https://github.com/bevyengine). Pardon our rough edges, and please consider [submitting an issue](https://github.com/TheBevyFlock/bevy_cli/issues) if you run into trouble!
+
+You can install the precompiled CLI using `cargo-binstall`:
+
+<!-- Update `X.Y.Z` with the correct version. -->
+
+```sh
+cargo binstall --git https://github.com/TheBevyFlock/bevy_cli --version X.Y.Z --locked bevy_cli
+```
+
+You may also compile the CLI yourself with `cargo install`:
+
+<!-- Update `cli-vX.Y.Z` with the correct tag. -->
+
+```sh
+cargo install --git https://github.com/TheBevyFlock/bevy_cli --tag cli-vX.Y.Z --locked bevy_cli
+```
+````
+
+5. Check the pre-release box if this is an alpha release, then click "Save draft".
+6. [Run the "Build CLI" workflow](https://github.com/TheBevyFlock/bevy_cli/actions/workflows/build-cli.yml), and make sure to check the "Upload to release" box.
+7. Ensure that the workflow has successfully uploaded all executables to the draft release, then press "Publish release"!
+8. Announce the release on Discord and other social medias. Congrats!
+
+## Post-Release
+
+1. Add a new unreleased section to the top of the changelog (`CHANGELOG.md`) from the following template:
+
+```markdown
+## [Unreleased]
+
+<!-- Update `cli-vX.Y.Z` in the link to point to the latest release tag. -->
+
+**All Changes**: [`cli-vX.Y.Z...main`](https://github.com/TheBevyFlock/bevy_cli/compare/cli-vX.Y.Z...main)
+```
+
+2. Bump the version in `Cargo.toml` to the next `-dev` version, and ensure `Cargo.lock` also updates.
+3. Commit your changes and open a pull request.
+4. Merge the PR once it has been approved, unblocking the feature freeze.
diff --git a/docs/src/contribute/linter/how-to/release.md b/docs/src/contribute/linter/how-to/release.md
@@ -2,11 +2,11 @@
 
 ## Kick-off Pull Request
 
-1. Review the changelog (`CHANGELOG.md`) and ensure that all notable changes have been documented.
+1. Review the changelog (`bevy_lint/CHANGELOG.md`) and ensure that all notable changes have been documented.
 2. Replace `[Unreleased]` heading with the version with the format `[vX.Y.Z] - YYYY-MM-DD`.
 3. Update the `**All Changes**` link to compare from `main` to the new tag `lint-vX.Y.Z`. (E.g. `lint-v0.1.0...main` to `lint-v0.1.0...lint-v0.2.0`.)
-4. Review the migration guide (`MIGRATION.md`) and ensure all breaking / significant changes from the previous version are documented.
-5. Remove the `-dev` suffix from the version in `Cargo.toml` and the compatibility table in `README.md`.
+4. Review the migration guide (`bevy_lint/MIGRATION.md`) and ensure all breaking / significant changes from the previous version are documented.
+5. Remove the `-dev` suffix from the version in `Cargo.toml` and the compatibility table in `bevy_lint/README.md`.
     - Please ensure that `Cargo.lock` also updates!
 6. Replace `--branch main` in `action.yml` with `--tag lint-vX.Y.Z`.
     - The `linter-action.yml` workflow may fail as the tag does not exist yet. This is fine!
@@ -61,7 +61,7 @@ rustup run nightly-YYYY-MM-DD cargo install \
 
 ## Post-Release
 
-1. Add a new unreleased section to the top of the changelog (`CHANGELOG.md`) from the following template:
+1. Add a new unreleased section to the top of the changelog (`bevy_lint/CHANGELOG.md`) from the following template:
 
 ```markdown
 ## [Unreleased]
diff --git a/docs/src/linter/changelog.md b/docs/src/linter/changelog.md
@@ -0,0 +1 @@
+{{#include ../../../bevy_lint/CHANGELOG.md}}
diff --git a/docs/src/linter/migration.md b/docs/src/linter/migration.md
@@ -0,0 +1 @@
+{{#include ../../../bevy_lint/MIGRATION.md}}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{{#include ../../../bevy_lint/CHANGELOG.md}}`