Skip to content

Commit

Permalink
docs: release template: update based on 1.28 learnings (#12356)
Browse files Browse the repository at this point in the history
This takes release issue changes and observations from #12109 with also having an eye towards the upcoming release process changes per #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 <[email protected]>

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <[email protected]>

* Addressing feedback about version string update in master

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <[email protected]>

* 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 <[email protected]>
  • Loading branch information
BigLep and rjan90 committed Aug 12, 2024
1 parent ee57331 commit 70b1b03
Showing 1 changed file with 120 additions and 36 deletions.
156 changes: 120 additions & 36 deletions documentation/misc/RELEASE_ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,54 +1,138 @@
> 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

<Date this release will ship on if everything goes to plan (week beginning...)>

## ✅ 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

See the final release notes!

## ⁉️ Do you have questions?

Leave a comment in this ticket!
Leave a comment in this ticket!

0 comments on commit 70b1b03

Please sign in to comment.