# Release guides

# espup

1. [Prepare the release](https://github.com/esp-rs/espup/pull/368)
- Update dependencies version
- Bump `espup` version
- Check that the MSRV hasnt changed: `cargo msrv`
- Check SemVer changes with: `cargo semver-checks check-release`
- Update Changelog
2. Create the tag and release: ` git tag vx.y.z && git push --tags`
3. Create a new GitHub release: https://github.com/esp-rs/espup/releases
1. Draft new release
2. Choose the recently created tag
3. Fill the fields
- Name: vx.y.z
- Body: Copy the content from CHANGELOG.md removing empty sections
4. Remove the `Set as the latest release` tick
5. `Publish release`
4. `Continuous Deployment` action should generate all the binaries and publish to crates.io the new version
- Once the action has finished, mark the new version as latest in GitHub releases
5. Publish release info in Mattermost and Matrix

🚀 New `espup` release: [`v0.7.0`](https://github.com/esp-rs/espup/releases/tag/v0.7.0). 

It now uses [GCC 13.2](https://github.com/espressif/crosstool-NG/releases/tag/esp-13.2.0_20230928), note that the `export-esp.sh` content will be updated, and also changes the looging messages and formatting. See full list of changes on the [release notes](https://github.com/esp-rs/espup/releases/tag/v0.7.0) or [CHANGELOG.md](https://github.com/esp-rs/espup/blob/main/CHANGELOG.md)

6. [Prepare next release cycle](https://github.com/esp-rs/espup/pull/370/)

# espflash

1. [Prepare the release](https://github.com/esp-rs/espflash/pull/446/files)
- Update dependencies version
- Bump `espflash`and `cargo-espflash` versions
- Check that the MSRV hasnt changed: `cargo msrv`
- Check SemVer changes for `espflash` with: `cargo semver-checks check-release`
- Update changelog
2. Create the tag and release: ` git tag vx.y.z && git push --tags`
3. Create a new GitHub release: https://github.com/esp-rs/espflash/releases
1. Draft new release
2. Choose the recently created tag
3. Fill the fields
- Name: x.y.z
- Body: Copy the content from CHANGELOG.md removing empty sections
4. Remove the `Set as the latest release` tick
5. `Publish release`
4. `Continuous Deployment` action should generate all the binaries and publish both `espflash` and `cargo-espflash` to crates.io: If done manually, make sure to publish `espflash` before `cargo-espflash`:
1. Publish `espflash`: In `espflash` folder, run `cargo publish`
2. Publish `cargo-espflash`: In `cargo-espflash` folder, run `cargo publish`
3. Check the book chapter about `espflash` and see if it requires any update for the new release
6. Mark the releases as `latest`
7. Publish release info in Mattermost and Matrix

🚀 New `espflash` and `cargo-espflash` release: [`v2.1.0`](https://github.com/esp-rs/espflash/releases/tag/v2.1.0). 

It introduces `erase-flash`, `erase-region`, and `erase-parts` subcommands and minor fixes. See full list of changes on the [release notes](https://github.com/esp-rs/espflash/releases/tag/v2.1.0) or [CHANGELOG.md](https://github.com/esp-rs/espflash/blob/main/CHANGELOG.md)

8. [Prepare next release cycle](https://github.com/esp-rs/espflash/pull/447/)

# Xtensa Rust (rust-build)

After esp-rs/rust has been rebased on top of the latest upstream stable:
1. Create a `build/<w.x.y.z>` branch
2. [Replace the current Xtensa Rust version in the repo for the new version ](https://github.com/esp-rs/rust-build/pull/234/files)
- Push this changes to the `build/<w.x.y.z>` branch
- A tag might also need to be created`git tag v<w.x.y.z> && git push --tags`
3. [Create a release](https://github.com/esp-rs/rust-build/releases)
- The release name should be: `v<w.x.y.z>`
- Note that it should include the `v`. Ex: `v1.75.0.0`
- Set branch `build/<w.x.y.z>` as target branch or the created tag.
- Untick "Set as the latest release"
- Tick "Set as a pre-release"
5. Execute the [`Build Xtensa Rust toolchain` action](https://github.com/esp-rs/rust-build/actions/workflows/build-rust-artifacts.yaml)
- Run the workflow from the `build/<w.x.y.z>` branch
- Verify that the Xtensa Rust version is aready be updated due to the previous step
- Fill the "Release tag", you can get the tag by navigating to the recently created release and copying the last part of the URL
- Choose the artifacts to build
6. Wait until all builds succeed
- Some jobs may fail, fix it and rerun the job
8. Perform some testing
9. Send notification to Matrix channel about the pre-release.
10. A few days later, after some proper testing has been done, edit Release, turn off Pre-release flag, set as Latest release and Save
11. Send notification to Matrix channel about the final release.
12. Upload new image tags to [espressif/idf-rust](https://hub.docker.com/r/espressif/idf-rust)
- Manually run the [Publish IDF-Rust Tags workflow](https://github.com/esp-rs/rust-build/actions/workflows/publish-idf-rust-tags.yml) with:
- Branch of rust-build to use pointing to main if the `build/<w.x.y.z>` branch was already merged to main, or pointing to `build/<w.x.y.z>` if has not been merged yet, but the branch is ready and feature complete.
- Version of Rust toolchain should be `<w.x.y.z>`.

# esp-pacs

1. If necessary, update `xtask` dependencies (notably `svd2rust`) and re-generate packages, e.g.

    cargo xtask generate esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3

2. Bump version numbers as needed. This is almost always an increase of the minor version, and can be done via the `xtask`, e.g.

    cargo xtask bump-version minor esp32 esp32c2 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3

3. Open a pull request including the above changes
4. Once merged, publish each package; this is currently done manually, e.g.

    cd esp32 && cargo publish

# esp-hal

## Pre-pre-release

Update various dependencies _before_ a testing round. I suggest updating at least one week before the scheduled release. At this time it's also good to check the MSRV, and the current "latest" release for Xtensa enabled Rust.

## Pre-release

1. Determine which packages need releases
- Not all packages need to be published with each release, currently which packages need publishing must be determined manually
- You can check the git history for each package to see if there have been any changes since the previous releases
- Remember to check repos outside of esp-hal, if they need a release too:
- `esp-wifi-sys`
- `esp-pacs`
2. Verify that dependent libraries still function as expected when using the updated HALs
- Update esp-generate to the latest git crate revisions
3. Ensure that the MSRV for the release has a released latest xtensa toolchain
4. Start updating related content:
* book
* update any version specific links
* check content is still relevant for new release (i.e, in case of deprecation of an API), or a better recommended method of doing something
* no_std training
* esp-generate

## Release preparation

1. Run `cargo xrelease plan` to prepare a release plan. If you are only releasing a certain crate (and its dependencies), run `cargo xrelease plan <crate name>`.
* If needed, you can create a release from a side brach, by using `--allow-non-default`. You'll need to merge necessary changes, like documentation updates, back to `main` manually if needed.
3. Open the generated `release_plan.jsonc`, read the comment in it.
* Make changes to the plan if necessary. The order of the list items determines the order in which the packages are released. If you modify the version bump amount, you don't need to modify the new version or the tag name in this plan.
4. When ready, run `cargo xrelease execute-plan --no-dry-run` to prepare changes and open a release pull request.
* If you modified the release plan, this command will re-generate it for you to make sure the versions and tag names are updated according to the version bump amounts.
* The tool creates a new branch, switches to it, commits changes and pushes the branch to `origin`.
* The tool will try to open github for you to create a pull request. If all goes well, you just need to press `Create Pull Request`.
* If you are releasing lots of crates at once, the PR link may be longer than GitHub allows. In this case, the tool prints the PR description it wants you to use.
5. Review the generated pull request.
* The tool is expected to update crate versions in the repo, including package versions in dependencies.
* The tool is expected to finalize and clean up the changelog (update headings, remove empty groups, remove empty lines).
* The tool is expected to update the migration guide with the released version number.
* The xtask should generate new semver baseline files.
* The PR should create a new documentation preview.

> If the command fails, make sure to switch back to the main branch, delete the release branch, and make sure you also delete the release branch on `origin`.

6.

## Release

0. IMPORTANT: ensure the esp-generate PR is ready, and green using the esp-hal release branch. This is the final check before merging the PR and committing to the release.
1. Merge the release PR
2. Make sure you have the `release_plan.jsonc` with the same content as in the release PR description.
3. Run `cargo xrelease publish-plan --no-dry-run`
* The tool is expected to create new tags and push them to `esp-rs/esp-hal`
* The tool is expected to publish packages to crates.io
4. Create a Github release with the notes and migration guide
- Don't forget to create new migration guides!
5. Run the documentation workflow; this currently must be invoked manually

## Post-release

1. Update dependent repositories:
- esp-generate
- esp-openthread
- no_std-training
- Others???

# xtensa-toolchain

1. Verify that the action is wokring with some repository that uses it
- A fork of it may be required
2. Create a tag for the release. Eg: `git tag v1.5.2 && git push --tags`
3. If its a patch version, delete the minor version in GitHub and localy:
1. Delete the tag from https://github.com/esp-rs/xtensa-toolchain/tags
2. Locally. Eg: `git tag -d v1.5`
3. Recreate it so it points at the latest patch release. Eg: `git tag v1.5 && git push --tags`
4. Create the release for the version:
- Mark the publishing to GitHub Market place
- Fill Title and Body as other releases
- Set at latest release

# esp-idf-part

1. [Prepare the release](https://github.com/esp-rs/esp-idf-part/pull/30)
- Update dependencies version
- Bump `esp-idf-part` version
- Check that the MSRV hasnt changed: `cargo msrv`
- Check SemVer changes with: `cargo semver-checks check-release`
2. Create the tag and release: ` git tag vx.y.z && git push --tags`
3. Create a new GitHub release: https://github.com/esp-rs/esp-idf-part/releases
1. Choose the recently created tag
2. Fill the fields
- Name: vx.y.z
- Body: Use generate release notes button from GH
3. `Publish release`
4. `Release` action should publish to crates.io the new version
5. Prepare next release cycle
6. Update `espflash` to use the new published version

# esp-flasher-stub

1. [Prepare the release](https://github.com/esp-rs/esp-flasher-stub/pull/61)
- Update dependencies version
- Bump `esp-flasher-stub` version
- Check that the MSRV hasnt changed: `cargo msrv`
2. Create the tag and release: ` git tag vx.y.z && git push --tags`
3. Create a new GitHub release: https://github.com/esp-rs/esp-flasher-stub/releases
1. Choose the recently created tag
2. Fill the fields
- Name: vx.y.z
- Body: Use generate release notes button from GH
3. `Publish release`

# esp-generate

1. [Prepare the release](https://github.com/esp-rs/esp-generate/pull/77)
- Update dependencies version
- Bump `esp-generate` version
- Check that the MSRV hasnt changed: `cargo msrv`
- Update Changelog
2. Create the tag and release: ` git tag vx.y.z && git push --tags`
3. Create a new GitHub release: https://github.com/esp-rs/esp-generate/releases
1. Draft new release
2. Choose the recently created tag
3. Fill the fields
- Name: vx.y.z
- Body: Copy the content from CHANGELOG.md removing empty sections
4. Remove the `Set as the latest release` tick
5. `Publish release`
4. Check the book chapter about `esp-generate` and see if it requires any update for the new release
5. `Continuous Deployment` action should generate all the binaries and publish to crates.io the new version
- Once the action has finished, mark the new version as latest in GitHub releases
6. Publish release info in Mattermost and Matrix

🚀 New `esp-generate` release: [`v0.3.0`](https://github.com/esp-rs/esp-generate/releases/tag/v0.3.0). 

7. Prepare next release cycle