Revised Lotus Node/Client Versioning

[rjan90]

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

Beta Give feedback

1.  Communicate new versioning strategy in a discussion post: 3 Key Changes to the Lotus Release Process #12020
2. UpdateLOTUS_RELEASE_FLOW.md to reflect the new versioning strategy.
3. Update release process to have a step for updating the Lotus version for all docs: ipdx: auto update docs on version changes (support new release system) lotus-docs#746
4. Visual/text covering branch strategy and timelines
5. Deprecate the "releases" branch #12374
   4 of 4
   +0
   

[BigLep]

@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]

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]

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]

@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]

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]

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]

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]

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

[BigLep]

@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]

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