search

filecoin-project / lotus

Reference implementation of the Filecoin protocol, written in Go
https://lotus.filecoin.io/
Other
2.83k stars 1.26k forks source link

Revised Lotus Node/Client Versioning #12072

Closed rjan90 closed 3 weeks ago

rjan90 commented 3 months ago

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:

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).

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
- [x] Communicate new versioning strategy in a discussion post: https://github.com/filecoin-project/lotus/discussions/12020
- [x] Update[LOTUS_RELEASE_FLOW.md](https://github.com/filecoin-project/lotus/blob/master/LOTUS_RELEASE_FLOW.md) to reflect the new versioning strategy.
- [ ] Update release process to have a step for updating the Lotus version for all docs: https://github.com/filecoin-project/lotus-docs/pull/746
- [ ] Visual/text covering branch strategy and timelines
- [ ] https://github.com/filecoin-project/lotus/issues/12374
BigLep commented 3 months ago

@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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

@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 https://github.com/filecoin-project/lotus/discussions/12020#discussioncomment-9841776 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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

I have started a draft PR for updating the LOTUS_RELEASE_FLOW.md document here: https://github.com/filecoin-project/lotus/pull/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 commented 1 month ago

The subset of work for deprecating the releases branch was pulled out in https://github.com/filecoin-project/lotus/issues/12374

BigLep commented 3 weeks ago

@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 https://github.com/filecoin-project/lotus-docs/pull/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 commented 3 weeks ago

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