Skip to content

Commit

Permalink
docs: update LOTUS_RELEASE_FLOW with recent FAQs and branch/tag strat…
Browse files Browse the repository at this point in the history
…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>
  • Loading branch information
BigLep and rjan90 committed Aug 12, 2024
1 parent 4a37fa7 commit ba44b6b
Showing 1 changed file with 30 additions and 0 deletions.
30 changes: 30 additions & 0 deletions LOTUS_RELEASE_FLOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,12 +95,42 @@ By policy, the team will usually wait until about 3 weeks after the final releas

Unless a security issue is actively being exploited or a significant number of users are unable to update to the latest version, security fixes will not be backported to previous releases.

## Branch and Tag Strategy

> [!NOTE]
> - <span style="color:blue">Blue text</span> indicates node-related information.
> - <span style="color:orange">Orange text</span> indicates miner-related information.
> - System default colored text applies to both node and miner releases.
* <span style="color:blue">Node release branches are named `release/vX.Y.Z`</span>
* <span style="color:orange">Miner release branches are named `release/miner/vX.Y.Z`</span>
* By the end of the release process:
* <span style="color:blue">A `release/vX.Y.Z` branch (node) will have an associated `vX.Y.Z` tag</span>
* <span style="color:orange">A `release/miner/vX.Y.Z` branch (miner) will have an associated `miner/vX.Y.Z` tag</span>
* Both node and miner releases may have additional `vX.Y.Z-rcN` or `miner/vX.Y.Z-rcN` tags for release candidates
* The `master` branch is typically the source for creating release branches
* For emergency patch releases where we can't risk including recent `master` changes:
* <span style="color:blue">Node: `release/vX.Y.Z+1` will be created from `release/vX.Y.Z`</span>
* <span style="color:orange">Miner: `release/miner/vX.Y.Z+1` will be created from `release/miner/vX.Y.Z`</span>

## FAQ

### Why aren't Go major versions used more?

Golang tightly couples source code with versioning (major versions beyond v1 leak into import paths). This poses logistical difficulties to using major versions here. Using major versions for every network upgrade would disrupt every downstream library/application that consumes the native Lotus API, even if it brought zero expectation of breakage for the Golang APIs they depend on.

### Do more frequent Lotus releases mean a change to network upgrade schedules?

No. The starting-in-2024Q3 goal of more frequent (every 4 weeks) Lotus releases does not mean that there will be changes in the network upgrade schedule. At least as of 202408, the current cadence of Filecoin network upgrades is ~3 per year. We expect to usually uphold a 2 weeks upgrade time between a Lotus release candidate and a network upgrade on the Calibration network, and a 3 week upgrade time for a network upgrade on the Mainnet.

### How often exchanges and key stakeholders need to upgrade?

It´s hard to say how often they have to upgrade! If they do not encounter any issues with the current release they are on, and there are no new releases with vulnerability patches or an associated network upgrade, then upgrading is unnecessary. The goal for faster releases (and also having client and miner releases seperated) is to be able to bring bug-fixes and features faster to end-users that need them. Per discussion above, users are still encouraged to consider upgrading more frequently than the ~3 network upgrades per year to reap the benefits of improved software and to have a smaller batch of changes to vet before a network upgrade.

### How much new code will a release with an associated network upgrade include?

Releases 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 previously. This is a simplifier for Lotus maintainer, 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.

## Related Items

1. Release Issue template
Expand Down

0 comments on commit ba44b6b

Please sign in to comment.