docs: update FWSS upgrade checklist#508
Conversation
|
Added a follow-up update to incorporate the release/tagging process feedback from the Notion doc: https://app.notion.com/p/filecoindev/202606-PDP-FWSS-Contract-Deployment-Tagging-Deployment-Process-Updates-376dc41950c180c893e8f5e23189e393#376dc41950c180689e17c24f3060bb53 That feedback is reflected in the checklist via the tag-first / GitHub pre-release flow, release-page rollout tracking, stack vs component version tracking, CHANGELOG simplification, and post-switch |
BigLep
left a comment
BigLep
left a comment
There was a problem hiding this comment.
I know this isn't ready for review, but I'm dropping in on this in thinking about this upcoming 1.3.0 release and https://app.notion.com/p/filecoindev/202606-PDP-FWSS-Contract-Deployment-Tagging-Deployment-Process-Updates-376dc41950c180c893e8f5e23189e393#376dc41950c180689e17c24f3060bb53
No expectation to engage right now, but passing these on in case it's helpful for connecting template updates I was imagining from https://app.notion.com/p/filecoindev/202606-PDP-FWSS-Contract-Deployment-Tagging-Deployment-Process-Updates-376dc41950c180c893e8f5e23189e393#376dc41950c180689e17c24f3060bb53
| - [ ] All intended FWSS contract changes are merged into `main` | ||
| - [ ] Create release branch from `main` (recommended: `{{RELEASE_BRANCH}}`) | ||
| - [ ] Review this issue template on the release branch and make any one-off wording or structure tweaks before generating the release issue | ||
| - [ ] Create the release issue by running the [Create Release Issue]({{CREATE_ISSUE_WORKFLOW_LINK}}) workflow from this branch |
There was a problem hiding this comment.
I assume we still want to "Create the release issue by running the Create Release Issue"?
| - [ ] Changelog entry prepared in [CHANGELOG.md]({{CHANGELOG_LINK}}) | ||
| - [ ] Version string updated in [FilecoinWarmStorageService.sol]({{FWSS_CONTRACT_LINK}}) | ||
| - [ ] Upgrade PR created with the title `{{RECOMMENDED_PR_TITLE}}` and linked in the Overview section of this issue | ||
| - [ ] Changelog/release-notes PR opened for review with a Deployment note linking to the GitHub Release page for rollout status, addresses, and transaction links |
There was a problem hiding this comment.
| - [ ] Changelog/release-notes PR opened for review with a Deployment note linking to the GitHub Release page for rollout status, addresses, and transaction links | |
| - [ ] Changelog/release-notes PR opened for review with a Deployment note linking to the [GitHub Release page](https://github.com/FilOzone/filecoin-services/releases/tag/v{{RELEASE_VERSION}}) for rollout status, addresses, and transaction links |
| - [ ] Version string updated in [FilecoinWarmStorageService.sol]({{FWSS_CONTRACT_LINK}}) | ||
| - [ ] Upgrade PR created with the title `{{RECOMMENDED_PR_TITLE}}` and linked in the Overview section of this issue | ||
| - [ ] Changelog/release-notes PR opened for review with a Deployment note linking to the GitHub Release page for rollout status, addresses, and transaction links | ||
| - [ ] Version bump PR created with the title `{{RECOMMENDED_PR_TITLE}}`, including the `FilecoinWarmStorageService` `VERSION()` bump |
There was a problem hiding this comment.
A couple of things:
- This is is for the case where FWSS itself is changing. Do we want to denote that?
- We now have two PRs open (changelog PR and version bump). Consolidate to one?
| ``` | ||
|
|
||
| - [ ] Release issue Overview updated with PR links, summary, and action required | ||
| - [ ] Create the GitHub Release from `{{RELEASE_VERSION}}`, mark it as a pre-release, and include component versions plus a FWSS rollout status table |
There was a problem hiding this comment.
Maybe provide a CLI command for this to make sure it's prerelease and to to get the template (maybe drawing from https://app.notion.com/p/filecoindev/202606-PDP-FWSS-Contract-Deployment-Tagging-Deployment-Process-Updates-376dc41950c180c893e8f5e23189e393?source=copy_link#376dc41950c1809ead84daeed8d6c633 )?
Although I guess an agent will do most of this, so the key thing is to be clear with the agent about how you want the release page to look.
| - [ ] Merge release-prep/changelog PRs if still open, keeping mutable rollout details on the GitHub Release page | ||
| - [ ] Promote the GitHub Release from pre-release to latest after Mainnet proxy switch, checks, and release-page status are complete | ||
| - [ ] Merge auto-generated PRs in [filecoin-cloud](https://github.com/FilOzone/filecoin-cloud/pulls) | ||
| - [ ] Create "Upgrade Synapse to use newest contracts" issue |
There was a problem hiding this comment.
This can be removed now right because of the automation? Although we do need a step before for making sure that PR actually got merged.
| - `deployments.json` should match live on-chain state behind proxies. Prepare and merge its update after Safe execution, and include component version fields when the schema supports them. | ||
| - Use the GitHub Release page for mutable rollout details. CHANGELOG entries should describe what changed and link to the release page for deployment addresses, epochs, and txs. |
There was a problem hiding this comment.
These belong in a Notes From v1.3.0 section?
| ``` | ||
|
|
||
| - [ ] Version bump PR merged so `main` contains the final `FilecoinWarmStorageService` version string | ||
| - [ ] Create release branch from `main` after the version bump lands (recommended: `{{RELEASE_BRANCH}}`) |
There was a problem hiding this comment.
What work do we expect to do in the branch, or is it just there for if we need to get a patch release out? Maybe we make this clear?
BigLep
left a comment
BigLep
left a comment
There was a problem hiding this comment.
This is Steve's Claude agent that has all the context from iterating on the tag-first release process proposal. Overall this is a strong implementation of the proposal. A few comments below — some reinforcing Steve's feedback, some additional.
|
|
||
| ### Component Versions | ||
|
|
||
| | Component | Version | Changed? | Notes | |
There was a problem hiding this comment.
FilecoinWarmStorageService has Changed? defaulting to Yes and PDPVerifier defaulting to No. For PDP-only stack bumps, FWSS won't change; for a release that upgrades both, PDP would be Yes. Consider defaulting both to TBD so the release engineer fills them in, rather than having to remember to override the defaults.
|
|
||
| | Validation | Evidence/status | | ||
| |---|---| | ||
| | foc-devnet post-upgrade state validation | `TBD` | |
There was a problem hiding this comment.
Consider adding a row for Synapse SDK integration build, since the Synapse PR will already exist by this point (opened in Phase 1 by the tag push). That would give you early signal if the contract changes break synapse-core compilation.
| @@ -88,25 +154,38 @@ For each network, record evidence that: | |||
|
|
|||
| ## Release Checklist | |||
There was a problem hiding this comment.
+1 to Steve's comment on line 97 about the missing "Create Release Issue" step. The release issue is the operator runbook per the operating rules — it should still be generated here in Phase 1, probably right after the release branch is created (since the workflow renders from the branch's copy of the template).
| - [ ] Version string updated in [FilecoinWarmStorageService.sol]({{FWSS_CONTRACT_LINK}}) | ||
| - [ ] Upgrade PR created with the title `{{RECOMMENDED_PR_TITLE}}` and linked in the Overview section of this issue | ||
| - [ ] Changelog/release-notes PR opened for review with a Deployment note linking to the GitHub Release page for rollout status, addresses, and transaction links | ||
| - [ ] Version bump PR created with the title `{{RECOMMENDED_PR_TITLE}}`, including the `FilecoinWarmStorageService` `VERSION()` bump |
There was a problem hiding this comment.
+1 to Steve's comment. Consolidating changelog + version bump into a single release-prep PR would be simpler. Two PRs for what is conceptually one action ("prepare for release") adds coordination overhead.
On point 1 (FWSS-only case): for PDP-only stack bumps, there's no FWSS VERSION() bump, so neither this checklist item nor the version bump step would apply. Worth noting somewhere that for PDP-only releases, Phase 1 is just the submodule bump PR (which will be automated) + tag + pre-release.
| ``` | ||
|
|
||
| - [ ] Version bump PR merged so `main` contains the final `FilecoinWarmStorageService` version string | ||
| - [ ] Create release branch from `main` after the version bump lands (recommended: `{{RELEASE_BRANCH}}`) |
There was a problem hiding this comment.
+1 to Steve's question. The release branch serves two purposes worth documenting: (1) stable ref for running the "Create Release Issue" workflow (so the rendered issue uses this branch's copy of the template), and (2) landing spot for hotfix patches during rollout without blocking main.
| ``` | ||
|
|
||
| - [ ] Release issue Overview updated with PR links, summary, and action required | ||
| - [ ] Create the GitHub Release from `{{RELEASE_VERSION}}`, mark it as a pre-release, and include component versions plus a FWSS rollout status table |
There was a problem hiding this comment.
+1 to Steve's suggestion. A concrete gh release create snippet would make this copy-pasteable:
gh release create {{RELEASE_VERSION}} \
--prerelease \
--title "{{RELEASE_VERSION}}" \
--notes-file release-notes.mdThe release page template from the proposal (component version table + rollout status table per network) could be inlined here or referenced.
| @@ -193,8 +273,8 @@ CALLDATA_ONLY=true ./warm-storage-execute-upgrade.sh | |||
| export ETH_RPC_URL="https://api.calibration.node.glif.io/rpc/v1" | |||
| export FWSS_PROXY_ADDRESS="0x02925630df557F957f70E112bA06e50965417CA0" | |||
There was a problem hiding this comment.
This defaults EXPECTED_FWSS_VERSION to {{RELEASE_VERSION}} with an inline comment to override. For PDP-only stack bumps where stackVersion > fwssVersion, this default will be wrong — e.g., stack v1.2.2 but FWSS contract still returns 1.2.0. The comment is easy to miss.
Consider adding a {{FWSS_VERSION}} template variable to the renderer (create-upgrade-announcement.js) so this is explicit rather than relying on a comment override. Same issue applies at line 361.
| - [ ] Merge release-prep/changelog PRs if still open, keeping mutable rollout details on the GitHub Release page | ||
| - [ ] Promote the GitHub Release from pre-release to latest after Mainnet proxy switch, checks, and release-page status are complete | ||
| - [ ] Merge auto-generated PRs in [filecoin-cloud](https://github.com/FilOzone/filecoin-cloud/pulls) | ||
| - [ ] Create "Upgrade Synapse to use newest contracts" issue |
There was a problem hiding this comment.
+1 to Steve's comment. Since notify-synapse-sdk.yml fires on the tag push in Phase 1 and there's already a checklist item to confirm the Synapse SDK PR was opened, this manual "create issue" step is a leftover from the old process. Consider replacing with: "Confirm the Synapse SDK PR from Phase 1 is merged or has an owner."
| - StateView changes are intentionally left out of the default checklist. If a release needs a new StateView, add a clearly labeled exception section to the release issue and track it explicitly there. | ||
| - `deployments.json` should match live on-chain state. If you prepare updates before a Safe tx executes, verify on-chain before merging. | ||
| - `deployments.json` should match live on-chain state behind proxies. Prepare and merge its update after Safe execution, and include component version fields when the schema supports them. | ||
| - Use the GitHub Release page for mutable rollout details. CHANGELOG entries should describe what changed and link to the release page for deployment addresses, epochs, and txs. |
There was a problem hiding this comment.
+1 to Steve. The new operating rules and lessons belong in a "Notes From v1.3.0" section, following the existing pattern with "Notes From v1.2.0" at the bottom of the file.
|
TODO: we need to have something in her for catching changes to the view contract to avoid #509 (comment) . We then need steps for setting the view contract as well. |
|
TODO: consider adding a validation step to ensure pricing is what we expect (https://filecoinproject.slack.com/archives/C08TVNKJV7C/p1780946196664809?thread_ts=1780930384.256979&cid=C08TVNKJV7C ) |
|
TODO: handle when we're deploying breaking changes with filecoin-services and we don't have a Synapse release/tag can point users too: https://filecoinproject.slack.com/archives/C08TVNKJV7C/p1780930604191319 |
|
TODO: handle deploying all dependencies per https://filecoinproject.slack.com/archives/C08TVNKJV7C/p1781024659246519?thread_ts=1781023514.884269&cid=C08TVNKJV7C |
|
TODO: step for library ABI publishing: #522 |
|
TODO: decide what we want the version tag to represent: the commit that was deployed or the commit at the end of the release. Technically the contracts are deployed from https://github.com/FilOzone/filecoin-services/tree/release-v1.3.0. But a lot of the information about addresses / etc are not know until after the fact. We dodged this with avoiding changelog updates, there are still deployment.json changes. Maybe we use 2 tags? Does anyone care? If you do tag after the fact, then you have to deal with other commits making their way in: |
3 participants
Summary
createDataSetvalidation gates while keeping the Run Log concisedeployments.jsonfollow-upAddresses #502.
Validation
NETWORK=Mainnet UPGRADE_TYPE=Routine RELEASE_VERSION=v9.9.9 node .github/scripts/create-upgrade-announcement.js --dry-rungit diff --check