Skip to content
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.

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

Revised Lotus Node/Client Versioning #12072

Closed
3 of 5 tasks
rjan90 opened this issue Jun 6, 2024 · 10 comments
Closed
3 of 5 tasks

Revised Lotus Node/Client Versioning #12072

rjan90 opened this issue Jun 6, 2024 · 10 comments
Milestone

Comments

@rjan90
Copy link
Contributor

rjan90 commented Jun 6, 2024

This is a tracking issue for revising the Lotus Versioning

Problem to solve

We need to revise the versioning strategy of Lotus to adopt a more user-friendly approach, moving away from the mandatory (even) and feature release (odd) versioning scheme that has been the norm for the last years.

Why Important

Since LOTUS_RELEASE_FLOW.md was first written ~3 years ago, Lotus' stability and release quality have both increased. This proposal minimizes the need for having a "mandatory even" version that can be easily patched. Instead, by default, a hotfix can be applied to the latest production release, even if it includes additional backwards compatible features since the last network upgrade.

Historical Context

Historically, Lotus used an even and odd versioning scheme where even minor versions indicated mandatory releases (network upgrades) and odd minor versions indicated feature releases.

Reasons for Change

  1. Building a Great Blockchain Client: The goal is to make the Lotus Client a great blockchain client that people can build upon, enhancing its usability and appeal to developers and users alike.
  2. Decoupling Versioning: We are decoupling the versioning for Lotus Miner and Lotus Client to allow for more independent development and release cycles.
  3. Increased Stability: Over the past few years, Lotus' stability and release quality have improved significantly, reducing the need for a strict even/odd versioning scheme.
  4. Simplified Versioning: A more straightforward versioning strategy (MAJOR.MINOR.PATCH) will be easier for users to understand and follow.
  5. Clear Communication: The new strategy will clearly highlight whether a release is optional or mandatory for network upgrades in the release changelog, reducing confusion.

User/Customer

Lotus Client users

Notes

After the Lotus v1.28.0 release, which brings the changes for the next network upgrade (nv23), we will move away from the even and odd versioning.

The format will be MAJOR.MINOR.PATCH:

  • Increment MAJOR if there are major changes to Lotus (e.g., if we re-architect).
  • Increment MINOR whenever there is a network upgrade, API breaking change, or non-backwards-compatible feature enhancements.
  • Increment PATCH whenever there are backwards-compatible bug fixes or feature enhancements.

Concerning branching:

  1. Releases will branch from master, regarldess if the release is for a network upgrade or not.
  2. Commits will almost always land in master.
  3. Commits may be cherry-picked into a release branch. This could occur when rushing out a release or during the RC phase of a release.
  4. There is no more "releases" branch.

A key callout is that a Lotus release that has the functionality for a network upgrade may likely have commits that haven't been deployed to production yet (besides new FIP functionality).

  • Before: "mandatory" releases had "last production release + minimum commits necessary for network upgrade"
  • Now: release for a network upgrade will have "last production release + minimum commits necessary for network upgrade + any other commits that have made it into master since the last production release".
    This means a release accompanying a network upgrade may have commits that aren't essential and haven't been deployed to production. This is a simplifier and we think the risk is acceptable because we'll be doing releases more frequently (thus the amount of commits that haven't made it to a production release will be smaller) and our testing quality has improved since years past. (There is more discussion on this here.)

We expect:

  1. to be doing releases every ~4 weeks, except during network upgrade times given they have longer RC periods.
  2. reduce the RC period for releases that don't accompany a network upgrade to ~1 week.

Tasks

  1. 4 of 4
    BigLep rjan90
@rjan90 rjan90 added this to the DX-Streamline milestone Jun 6, 2024
@BigLep
Copy link
Member

BigLep commented Jun 6, 2024

@rjan90 : I'm putting things down about lotus docs that are triggering about release versions when reading through them:

  1. I don't know how/when lotus docs get updated, but I see they current point to the latest "mandatory even" release (e.g., 1.26.0) in https://lotus.filecoin.io/lotus/install/linux/ . I assume this process/scripting will need to be updated to just use the "highest number" release.
  2. "The releases branch always contains the latest stable release for Lotus" - I assume this is a statement that needs to be reevaluated.

@rjan90
Copy link
Contributor Author

rjan90 commented Jun 7, 2024

I don't know how/when lotus docs get updated, but I see they current point to the latest "mandatory even" release (e.g., 1.26.0) in https://lotus.filecoin.io/lotus/install/linux/ . I assume this process/scripting will need to be updated to just use the "highest number" release.

I think using the highest number release would be ideal. Currently the process of updating the version for the Downloading from Github (and a couple of other places) is done manully every network upgrade.

Edit: This should also have been poiting to v1.26.2 or v1.26.3. v1.26.0 will not sync the current mainnet. So current process is human error prone.

@BigLep
Copy link
Member

BigLep commented Jun 7, 2024

This should also have been poiting to v1.26.2 or v1.26.3. v1.26.0 will not sync the current mainnet. So current process is human error prone.

Understood. I added a subtask for "Update release process to have a step for updating the Lotus version for all docs". Ideally we automate this, but at the minimum it needs to be in the checklist so it doesn't get forgotten.

@BigLep
Copy link
Member

BigLep commented Jun 21, 2024

@rjan90 : I assume as part of this we want to also make the shift to always branch from master, even for network upgrade related releases? I didn't see that stated anywhere. I created a discussion reply on it in #12020 (comment) so we can confirm that's the case. If it is, we'll need to add some done criteria and tasks to the tasklist of this issue.

@BigLep
Copy link
Member

BigLep commented Jul 13, 2024

If it is, we'll need to add some done criteria and tasks to the tasklist of this issue.

I did some issue description updates discussing branch strategy and timing.

@BigLep
Copy link
Member

BigLep commented Jul 24, 2024

When this gets taken on lets also discuss:

  1. Branch names. For example, when we start the release process for v1.29.0, I assume that will be in a release/v1.29.x branch. The v1.29.0 tag will point to that branch. For a 1.29.1, we would cherrypick changes from master into the release/v1.29.x branch and then tag 1.29.1 from the release/v1.29.x branch.
  2. Discussion on what merges we use when (e.g., merge commits vs. squash merging vs. rebase merging) as there has been inconsistency here and it has caused pain.

@rjan90
Copy link
Contributor Author

rjan90 commented Jul 30, 2024

I have started a draft PR for updating the LOTUS_RELEASE_FLOW.md document here: #12322. It is very preliminary, and there are items/discussions in this issue ticket that we need to discuss and figure out, that needs to be updated in that PR.

BigLep added a commit that referenced this issue Aug 8, 2024
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.
BigLep added a commit that referenced this issue Aug 9, 2024
…egy items

This was done as additional content to potentially add per #12322 .  It includes content I saw in #12020 and #12072 that wasn't previously included.
rjan90 added a commit that referenced this issue Aug 9, 2024
…egy items (#12364)

* docs: update LOTUS_RELEASE_FLOW with recent FAQs and branch/tag strategy items

This was done as additional content to potentially add per #12322 .  It includes content I saw in #12020 and #12072 that wasn't previously included.

* Updates from self-review.

* docs: Clarify node/miner release branching

docs: Clarify node/miner release branching

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@protocol.ai>

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@protocol.ai>

---------

Co-authored-by: Phi <orjan.roren@gmail.com>
BigLep added a commit that referenced this issue Aug 9, 2024
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 <orjan.roren@gmail.com>

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* Addressing feedback about version string update in master

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* 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 <orjan.roren@gmail.com>
BigLep added a commit that referenced this issue Aug 10, 2024
@BigLep
Copy link
Member

BigLep commented Aug 10, 2024

The subset of work for deprecating the releases branch was pulled out in #12374

rjan90 added a commit to hanabi1224/lotus that referenced this issue Aug 12, 2024
…ect#12356)

This takes release issue changes and observations from filecoin-project#12109 with also having an eye towards the upcoming release process changes per filecoin-project#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 <orjan.roren@gmail.com>

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* Addressing feedback about version string update in master

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* 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 <orjan.roren@gmail.com>
rjan90 added a commit that referenced this issue Aug 12, 2024
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 <orjan.roren@gmail.com>

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* Addressing feedback about version string update in master

* Update documentation/misc/RELEASE_ISSUE_TEMPLATE.md

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* 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 <orjan.roren@gmail.com>
rjan90 added a commit that referenced this issue Aug 12, 2024
…egy items (#12364)

* docs: update LOTUS_RELEASE_FLOW with recent FAQs and branch/tag strategy items

This was done as additional content to potentially add per #12322 .  It includes content I saw in #12020 and #12072 that wasn't previously included.

* Updates from self-review.

* docs: Clarify node/miner release branching

docs: Clarify node/miner release branching

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@protocol.ai>

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@protocol.ai>

---------

Co-authored-by: Phi <orjan.roren@gmail.com>
rjan90 added a commit that referenced this issue Aug 12, 2024
* Preliminary update to the LOTUS_RELEASE_FLOW document

Preliminary update to the LOTUS_RELEASE_FLOW document

* docs: update LOTUS_RELEASE_FLOW with recent FAQs and branch/tag strategy items (#12364)

* docs: update LOTUS_RELEASE_FLOW with recent FAQs and branch/tag strategy items

This was done as additional content to potentially add per #12322 .  It includes content I saw in #12020 and #12072 that wasn't previously included.

* Updates from self-review.

* docs: Clarify node/miner release branching

docs: Clarify node/miner release branching

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@protocol.ai>

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@protocol.ai>

---------

Co-authored-by: Phi <orjan.roren@gmail.com>

* Apply @BigLep suggestions from code review

These were self-committed to make it easier to propose additional changes on top.

* Apply remaining @BigLep suggestions from code review

* Added terminology section

* More editing
Major items were answering:
Why isn't Lotus Miner released more frequently?
Why is the `releases` branch deprecated and what are alternatives?

* Update LOTUS_RELEASE_FLOW.md

Co-authored-by: Steve Loeppky <biglep@filoz.org>

* fix: double spacing and minor typos

fix: double spacing and minor typos

* fix(docs): link to LOTUS_RELEASE_FLOW.md from CONTRIBUTING.md

fix(docs): link to LOTUS_RELEASE_FLOW.md from CONTRIBUTING.md

---------

Co-authored-by: Steve Loeppky <biglep@protocol.ai>
Co-authored-by: Steve Loeppky <biglep@filoz.org>
BigLep added a commit that referenced this issue Aug 13, 2024
* chose: deprecate "releases" branch by providing clear messaging

This is being done in support of #12072

* fix: restore contents of makefile

restore contents of makefile, which seems to have been deleted accidentally

* Revert "fix: restore contents of makefile"

This reverts commit 9de27df.

* Made the message stand out more and also print to STDERR

* Adjusted workflow actions in releases branch to not run on pull_request so they aren't triggered by changes to the releases branch

* Update Makefile

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

* Update Makefile

Co-authored-by: Phi-rjan <orjan.roren@gmail.com>

---------

Co-authored-by: Phi <orjan.roren@gmail.com>
@BigLep BigLep changed the title Revised Lotus Client Versioning Revised Lotus Node/Client Versioning Aug 19, 2024
@BigLep
Copy link
Member

BigLep commented Sep 9, 2024

@rjan90 : is there more you think we should do here? We had these items open:

Update release process to have a step for updating the Lotus version for all docs

I think this is covered in filecoin-project/lotus-docs#746 right?

Visual/text covering branch strategy and timelines

I had added this. While I think it's good so we're not so text heavy, I don't think it's a priority currently. I'd rather take it on the next time we have a discussion with ourselves or others and wish we had a diagram. At that point in time, it will be clearer on the specific diagram we want. While I could come up with something here, it's not sharp in my mind if someone said "You have one hour to go make a diagram that is useful for contributors. Go!"

As a result, I am good if we close this out unless you think there is more we ned to do here.

@rjan90
Copy link
Contributor Author

rjan90 commented Sep 10, 2024

As a result, I am good if we close this out unless you think there is more we ned to do here.

Agreed that we can close this out now. Remaining tasks should be covered by lotus-docs#746

@rjan90 rjan90 closed this as completed Sep 10, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: ☑️ Done (Archive)
Development

No branches or pull requests

2 participants