From 70b1b03ea5174c1cd3176e5143f3ac9c86bc832b Mon Sep 17 00:00:00 2001 From: Steve Loeppky Date: Fri, 9 Aug 2024 13:36:32 -0700 Subject: [PATCH] docs: release template: update based on 1.28 learnings (#12356) This takes release issue changes and observations from https://github.com/filecoin-project/lotus/issues/12109 with also having an eye towards the upcoming release process changes per https://github.com/filecoin-project/lotus/issues/12072 . The general goals here are: 1. Have a checkbox step for each step a releae engineer should take. 2. Reduce duplication in the template itself. Where content should be duplicated, there is a comment for the issue creator to handle the copy/pasting. * Removed experimental syntax testing. * Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md * Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md * Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md * Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md Co-authored-by: Phi-rjan * Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md Co-authored-by: Phi-rjan * Addressing feedback about version string update in master * Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md Co-authored-by: Phi-rjan * Clarifying with comments that backport step doesn't really apply to RC1. * Cleanup Changelog prep steps. Addded some commands for helping identify holes in changelog. --------- Co-authored-by: Phi-rjan --- documentation/misc/RELEASE_ISSUE_TEMPLATE.md | 156 ++++++++++++++----- 1 file changed, 120 insertions(+), 36 deletions(-) diff --git a/documentation/misc/RELEASE_ISSUE_TEMPLATE.md b/documentation/misc/RELEASE_ISSUE_TEMPLATE.md index 639750faf9d..00c5970b104 100644 --- a/documentation/misc/RELEASE_ISSUE_TEMPLATE.md +++ b/documentation/misc/RELEASE_ISSUE_TEMPLATE.md @@ -1,49 +1,133 @@ > Release Issue Template -# Lotus X.Y.Z Release - -[//]: # (Open this issue as [WIP] Lotus vX.Y.Z) -[//]: # (Apply the `tpm` label to it, and pin the issue on GitHub) +# Lotus Node|Miner X.Y.Z Release + +[//]: # (Below are non-visible steps intended for the issue creator) +[//]: # (Start an issue with title "[WIP] Lotus Node|Miner vX.Y.Z" and adjust the title for whether it's a Node or Miner release.) +[//]: # (Copy in the content of https://github.com/filecoin-project/lotus/blob/master/documentation/misc/RELEASE_ISSUE_TEMPLATE.md) +[//]: # (Find/Replace "X.Y.Z" with the actual values.) +[//]: # (Copy/paste the "Release Checklist > RCX" section to "Release Checklist > Stable \(non-RC\) Release" and apply the "diff" called out there.) +[//]: # (Find/Replace "RCX" with "RC1".) +[//]: # (If this isn't a release tied to a network upgrade, remove all items with "\(network upgrade\)") +[//]: # (Adjust the "Meta" section values.) +[//]: # (Apply the `tpm` label to the issue) +[//]: # (Create the issue) +[//]: # (Pin the issue on GitHub) + +## πŸ˜Άβ€πŸŒ« Meta +* Scope: Node|Miner +* Is this linked with a network upgrade, and thus mandatory? Yes|No +* Related network upgrade version: n/a|nvXX ## 🚒 Estimated shipping date - - -## βœ… Release Checklist - -**Note for whoever is owning the release:** please capture notes as comments in this issue for anything you noticed that could be improved for future releases. There is a *Post Release* step below for incorporating changes back into the [RELEASE_ISSUE_TEMPLATE](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/RELEASE_ISSUE_TEMPLATE.md), and this is easier done by collecting notes from along the way rather than just thinking about it at the end. +[//]: # (If/when we know an exact date, remove the "week of".) +[//]: # (If a date week is an estimate, annotate with "estimate".) -- [ ] Fork a new branch (`release/vX.Y.Z` or `release/miner/vX.Y.Z`) from `master` and make any further release related changes to this branch. If any "non-trivial" changes get added to the release, uncheck all the checkboxes and return to this stage. -- [ ] Bump the version in `build/version.go` in the `master` branch to `vX.Y.(Z+1)-dev` (bump from feature release) or `vX.(Y+1).0-dev` (bump from mandatory release). Run make gen and make docsgen-cli before committing changes -- [ ] *Optional:* If preparing a release for a network upgrade, make sure all [Lotus dependecies are updated to the correct versions for the network upgrade](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/Update_Dependencies_Lotus.md) +| Candidate | Date | Release URL | +|-----------|------|-------------| +| RC1 | Week of YYYY-MM-DD | | +| Stable (non-RC) | Week of YYYY-MM-DD (estimate) | | -**Prepping an RC**: +## πŸͺ’ Dependencies for releases +> [!NOTE] +> 1. This is the set of changes that need to make it in for a given RC. This is effectively the set of changes to cherry-pick from master. +> 2. They can be checked as done once they land in `master`. +> 3. They are presented here for quick reference, but backporting is tracked in each `Release Checklist`. -Perform the following changes to the `release/vX.Y.Z` or `release/miner/vX.Y.Z` branch through a PR: -- [ ] Update the version string in `build/version.go` to one ending with '-rcX'. Ensure you update the appropriate version string based on whether you are creating a node release (`NodeBuildVersion`), a miner release (`MinerBuildVersion`) or both. -- [ ] run `make gen && make docsgen-cli` to generate documentation -- [ ] create a **PR** targetting `release/vX.Y.Z` or `release/miner/vX.Y.Z` branch - - Opening a PR will trigger a CI run that will build the release and publish it to GitHub as a draft - - Merging the PR will trigger a CI run that will publish the GitHub release (it will also create a git tag) +[//]: # (Copy/paste this for each RC, and increment "X") +### RCX +- [ ] To Be Added -**Testing** +### Stable (non-RC) +- [ ] To Be Added -Test the release candidate thoroughly, including automated and manual tests to ensure stability and functionality across various environments and scenarios. - -**Stable Release** - -Perform the following changes to the `release/vX.Y.Z` branch through a PR: -- [ ] update the version string in `build/version.go` to one **NOT** ending with '-rcX' -- [ ] run `make gen && make docsgen-cli` to generate documentation -- [ ] create a **PR** targetting `release/vX.Y.Z` or `release/miner/vX.Y.Z` branch - - Opening a PR will trigger a CI run that will build the release and publish it to GitHub as a draft - - Merging the PR will trigger a CI run that will publish the GitHub release (it will also create a git tag) - -**Post-Release** +## βœ… Release Checklist -- [ ] Open a pull request against the `master` branch with a merge of the `releases` branch. Conflict resolution should ignore the changes to `version.go` (keep the `-dev` version from master). Do NOT delete the `releases` branch when doing so! -- [ ] Update [RELEASE_ISSUE_TEMPLATE.md](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/RELEASE_ISSUE_TEMPLATE.md) with any improvements determined from this latest release iteration. -- [ ] Create an issue using [RELEASE_ISSUE_TEMPLATE.md](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/RELEASE_ISSUE_TEMPLATE.md) for the _next_ release. +### Before RC1 +- [ ] (network upgrade) Make sure all [Lotus dependencies are updated to the correct versions for the network upgrade](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/Update_Dependencies_Lotus.md) + - Link to Lotus PR: +- [ ] Open PR against [RELEASE_ISSUE_TEMPLATE.md](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/RELEASE_ISSUE_TEMPLATE.md) with title `docs(vX.Y.Z): release template improvements` for improving future releases. + - Link to PR: + - This will get merged in a `Post Release` step, but improvements are better done by collecting notes along the way rather than just thinking about it at the end. +- [ ] Fork a new branch (`release/vX.Y.Z` or `release/miner/vX.Y.Z`) from `master` and make any further release-related changes to this branch. +- `master` branch Version string updates + - [ ] bump the version(s) in `build/version.go` to `vX.Y.(Z+1)-dev`. + - Ensure to update the appropriate version string based on whether you are creating a node release (`NodeBuildVersion`), a miner release (`MinerBuildVersion`), or both. + - [ ] Run `make gen && make docsgen-cli` before committing changes. + - [ ] Create a PR with title `build(vX.Y.Z+1): set initial version string` + - Link to PR: + - [ ] Merge PR + +### RCs + +[//]: # (Copy/paste this "RCX" section for each additional RC, and increment "X") +#### RCX +> [!IMPORTANT] +> These PRs should be done in and target the `release/vX.Y.Z` or `release/miner/vX.Y.Z` branch. + +**Backport PR** + +[//]: # (For RC1 there likely isn't any backporting to do and thus no PR which reduces the steps.) +[//]: # (We do need all these steps for RC2 onwards though.) +[//]: # (If steps are removed for the RC1 checklist, they need to be preserved for future RCs/stable.) +[//]: # (For RC1 we still need to make sure the tracked items land though.) +- [ ] All explicitly tracked items from `Dependencies for releases` have landed +- [ ] Backported [everything with the "backport" label](https://github.com/filecoin-project/lotus/issues?q=label%3Arelease%2Fbackport+) +- [ ] Removed the "backport" label from all backported PRs (no ["backport" issues](https://github.com/filecoin-project/lotus/issues?q=label%3Arelease%2Fbackport+)) +- [ ] Create a PR with title `build(vX.Y.Z): backport changes for vX.Y.Z-rcX` + - Link to PR: +- [ ] Merge PR + +**Release PR** + +- [ ] Update the version string(s) in `build/version.go` to one ending with '-rcX'. + - Ensure to update the appropriate version string based on whether you are creating a node release (`NodeBuildVersion`), a miner release (`MinerBuildVersion`), or both. +- [ ] Run `make gen && make docsgen-cli` to generate documentation +- [ ] Changelog prep + - [ ] Editorial review (e.g., callout breaking changes, new features, FIPs, actor bundles) + - [ ] (network upgrade) Specify whether the Calibration or Mainnet upgrade epoch has been specified or not yet. + - Example where these weren't specified yet: [PR #12169](https://github.com/filecoin-project/lotus/pull/12169) + - [ ] Ensure no missing content when spot checking git history + - Example command looking at git commits: `git log --oneline --graph vA.B.C..`, where A.B.C correspond to the previous release. + - Example GitHub UI search looking at merged PRs into master: https://github.com/filecoin-project/lotus/pulls?q=is%3Apr+base%3Amaster+merged%3A%3EYYYY-MM-DD + - Example `gh` cli command looking at merged PRs into master and sorted by title to group similar areas: `gh pr list --repo filecoin-project/lotus --search "base:master merged:>YYYY-MM-DD" --json number,mergedAt,author,title | jq -r '.[] | [.number, mergedAt, .author.login, .title] | @tsv' | sort -k4 +- [ ] Create a PR with title `build(vX.Y.Z): release vX.Y.Z-rcX` + - Link to PR: + - Opening a PR will trigger a CI run that will build assets, create a draft GitHub release, and attach the assets. +- [ ] Merge the PR + - Opening the PR will trigger a CI run that will build assets, attach the assets to the GitHub release, publish the GitHub release, and create the corresponding git tag. + - [ ] Update `🚒 Estimated shipping date` table + - [ ] Comment on this issue announcing the RC + - Link to issue comment: + +### Testing +> [!NOTE] +> Link to any special steps for testing releases beyond ensuring CI is green. Steps can be inlined here or tracked elsewhere. + +### Stable (non-RC) Release + +[//]: # (This "NOTE" below with the "diff" to apply to the "RC copy/pasted content" is here to avoid the duplication in the template itself.) +[//]: # (This is done as a visible NOTE rather than a comment to make sure it's clear what needs to be added to this section.) +[//]: # (These comments ^^^ can be removed once the NOTE steps below are completed.) +> [!NOTE] +> Copy/paste in the `RCX` section above and then make these changes: +> 1. Change the version string text: +> +> Update the version string in `build/version.go` to one **NOT** ending with '-rcX' +> +> 2. Under "Changelog prep", add +> +> (network upgrade) Ensure the Mainnet upgrade epoch is specified. +> +> 3. Remove this `[!Note]` and the related invisible comments. + +### Post-Release + +- [ ] Open a pull request against `master` with a merge of the `release/vX.Y.Z` branch. + - [ ] Conflict resolution should ignore the changes to `version.go` (keep the `-dev` version from master). + - Link to PR: +- [ ] Finish updating/merging the [RELEASE_ISSUE_TEMPLATE.md](https://github.com/filecoin-project/lotus/blob/master/documentation/misc/RELEASE_ISSUE_TEMPLATE.md) PR from `Before RC1` with any improvements determined from this latest release iteration. ## ❀️ Contributors @@ -51,4 +135,4 @@ See the final release notes! ## ⁉️ Do you have questions? -Leave a comment in this ticket! +Leave a comment in this ticket! \ No newline at end of file