Skip to content

op-deployer: Add backports guide #14830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mslipper merged 1 commit into from
Mar 13, 2025
Merged

op-deployer: Add backports guide #14830

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 17 additions & 8 deletions op-deployer/book/src/reference-guide/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ dangerous!), you should use an earlier version of OP Deployer. This setup allows
breaking changes on `develop`, while still allowing new chains to be deployed and upgraded using production-ready smart
contracts.

Bugs that are fixed on develop will also be backported to earlier versions on a best-effort basis.

If you deploy from an HTTPS or file [locator](./artifacts-locators.md), the deployment behavior will match the
contract's tag. For example, if version `v0.2.0` supports `v2.0.0` then the deployment will work as if you were
deploying `op-contracts/v2.0.0`. Typically, errors like `unknown selector: <some hex>` imply that you're using the wrong
Expand All @@ -18,6 +16,17 @@ get one that works. Note that this workflow is **not recommended** for productio

[releases]: https://github.com/ethereum-optimism/optimism/releases

## Version Backports

From time to time, we may backport bugfixes from develop onto earlier versions of OP Deployer. The process for this is
as follows:

1. If one doesn't exist already, make a new branch for the version lineage you're patching (e.g. `v0.2.x`). This branch
should be based on the latest release of that lineage. The branch should be named as follows:
`backports/op-deployer/<lineage, i.e. v0.2.0>`.
2. Open a PR with the backport against that branch. Be sure to reference the original commit in the backport.
Copy link
Contributor

@bitwiseguy bitwiseguy Mar 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The exact sequence of commands we need to use is unclear to me. Does this sound correct?

git checkout -b backports/op-deployer/v0.2.0 op-deployer/v0.2.0 // backport branch off of tagged release
git cherry-pick <develop-commit-hash-1> <develop-commit-hash-2> // cherry-pick from main/develop
git push origin backports/op-deployer/v0.2.0

Should we just tag backports/op-deployer/v0.2.0 or op-deployer/v0.2.1 at this point? If not, what branch does the pr for backports/op-deployer/v0.2.0 target?

Copy link
Contributor

@yashvardhan-kukreja yashvardhan-kukreja Mar 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More like:

  • git checkout -b backports/op-deployer/v0.2.0 op-deployer/v0.2.0 // backport branch off of tagged release
  • git push origin backports/op-deployer/v0.2.0 // to push this new branch as it is on origin reflecting the current untouched state of v0.2.0
  • git checkout -b backport-containing-branch
  • git cherry-pick <commit-sha-of-your-fix-on-develop>
  • git push origin backport-containing-branch

Then, create a PR where source branch is backport-containing-branch and destination branch is backports/op-deployer/v0.2.0

Then, get that PR reviewed and merged.

Now, checkout a new tag called "v0.2.1" from the latest HEAD of backports/op-deployer/v0.2.0 and push it on origin.

Goreleaser will catch this newly pushed tag and automatically create the v0.2.1 release i.e. (v0.2.0 + your backported fix)

Copy link
Contributor

@bitwiseguy bitwiseguy Mar 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I'm almost with you. Seems maybe there is a typo in your push command (has an extra arg):

git checkout -b backports/op-deployer/v0.2.0 op-deployer/v0.2.0
git push origin backports/op-deployer/v0.2.0
git checkout -b op-deployer/v0.2.1 backports/op-deployer/v0.2.0
git cherry-pick
git push origin op-deployer/v0.2.1

So backports/op-deployer/v0.2.0 will be a long running branch (i.e. should never be deleted) where cherry picked commits will get merged. And after each merge into the backport branch, a new patch tag should be created.

Copy link
Contributor

@yashvardhan-kukreja yashvardhan-kukreja Mar 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So backports/op-deployer/v0.2.0 will be a long running branch (i.e. should never be deleted) where cherry picked commits will get merged.

✅

And after each merge into the backport branch, a new patch tag should be created.

Umm, that's not necessarily true but you're on the right track.
For example, if we're aware of 2-3 fixes at present worth getting backported, it's sensible to club them together in one PR or create them as separate PRs and merge them all onto the backports/op-deployer/v0.2.0.

So that once we finally make the release v0.2.1, it would contain all the backported fixes and not just one of them.

PS: Something similar's happening with op-deployer currently i.e. including my recent backported fix, there are some more backport-fixes which Slipper is working and planning include in the new release v0.0.13 eventually. (v0.0.11 + my backported fix + Slipper's backported fixes).

Copy link
Contributor

@bitwiseguy bitwiseguy Mar 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. Ok thanks for the patient explanation

Copy link
Contributor

@yashvardhan-kukreja yashvardhan-kukreja Mar 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But yeah, if you're talking about some time in the future (after v0.2.1 is already released), when we realise another fix worth backporting, I opine on having dedicated backport branches during the process of creating new backport releases i.e. new branch called backports/op-deployer/v0.2.1 (created out of v0.2.1 tag) so as to eventually create a new backport release v0.2.2

Functionally speaking, like you said, we can continue to just make a new commit on the old long-running backports/op-deployer/v0.2.0 and cut a release v0.2.2 from there but I think that would lead to some vagueness. One branch per backport release makes things more trackable imo.

3. Make and push a new tag on that lineage.

## Adding Support for New Contract Versions

Adding support for a new contract version is a multi-step process. Here's a high-level overview. For the sake of
Expand Down Expand Up @@ -56,16 +65,16 @@ Now, update `standard/standard.go` with these values so that the new artifacts t
const ContractsVXTag = "op-contracts/vX.Y.Z"

var taggedReleases = map[string]TaggedRelease{
// Other releases...
ContractsVXTag: {
ArtifactsHash: common.HexToHash("<the artifacts hash>"),
ContentHash: common.HexToHash("<the checksum>"),
},
// Other releases...
ContractsVXTag: {
ArtifactsHash: common.HexToHash("<the artifacts hash>"),
ContentHash: common.HexToHash("<the checksum>"),
},
}

// Update the L1/L2 versions accordingly
func IsSupportedL1Version(tag string) bool {
return tag == ContractsVXTag
return tag == ContractsVXTag
}
```

Expand Down