Overview of Proposal
Allow projects to switch from SemVer (Semantic Versioning) for their versioning to CalVer (Calender Versioning) for their versioning.
Besu is different from a lot of the Hyperledger project in that it is beholden to a standard (Ethereum Mainnet compatibility) that it does not control. While it participates in co-ordination of that standard Besu does not have simple control over it like the other DLT projects do.
When working with public networks such as Mainnet there is a critical need to use the most current version of Besu, no matter what the semantic compatibility is. Not dealing with a breaking change is the same as dropping the service. Mainnet is fairly good about maintaining backwards compatibility, but there are other smaller changes such as P2P network protocol upgrades and RPC APIs that update at an infrequent cadence.
Besu feels that a CalVer versioning for the main DLT release itself would better signal how aligned we are to the continually moving target of mainnet compatibility. We think it will also more clearly communicate multiple release streams should not be expected.
Formal Proposal(s)
Update the Release Taxonomy to allow project to opt into using Calendar Versioning (CalVer) instead of Semantic Versioning MAJOR.MINOR.PATCH versioning.
Projects that opt in must meet these criteria:
- The project has a regular or semi-regular release schedule that is oriented around release dates
- If there are different points in time where different release processes are used, those need to be documented.
- The project has an established policy for introducing breaking changes
- This policy must allow users sufficient time to adapt to the changes
- This policy must include the channels used to communicate this (such as prominent placement in CHANGELOG files)
- Some period of backward compatibility should exist.
For example, Besu's policy would be:
- Besu has triannual to quarterly major releases. These are numbered YY.M.0, such as 20.9.0.
- These releases undergo a two week beta and two week RC cycle,
- All supported public networks are synchronized and validated to stay in sync
- Besu has fortnightly patch releases. These are numbered YY.M.PATCH, such as 20.9.1
- These releases come off of continuous integration releases
- A smaller number of select networks are re-synchronized, and previously nodes are upgraded and observed for 24 hours prior to release.
- Breaking changes are only introduced in quarterly changes
- These should have an entire quarter of notice, for example if notice of a breaking change is given in 20.2.4 then 20.5.0 should not implement the change but instead warn that 20.8.0 will implement the change
- These must be placed prominently at the top of the CHANGELOG for the quarterly release and each patch release for the notice period should reference it.
- If Besu exposes external libraries (such as JNI libraries for cryptography), those should continue to use SemVer.
- Internal versioning of build modules will use CalVer, providing a clear delineation as to what is an API and what isn't.
Action Items
- Danno Ferrin to submit a corresponding PR to update the Release Taxonomy
Reviewed By
- Angelo De Caro
- Arnaud J Le Hors
- Christopher Ferris
- Dan Middleton
- Gari Singh
- Hart Montgomery
- Mark Wagner
- Nathan George
- Swetha Repakula
- Tracy Kuhrt
- Troy Ronda
8 Comments
Tracy Kuhrt
I am curious about the bolded statement and how it applies to projects using Besu in a private permissioned setting?
Danno Ferrin
Yep, that is a bit of my blindspot since most of the EEA work is handled by maintainers out of the APAC region and I focus mostly on the miannet pieces, which drive most of the codebase changes currently. I revised it to emphasize the mainnet essentiality.
The principal sources of incompatibility for private permissioned settings would be the introduction of features added to mainnet hard forks, such as new encryption primitives in the EVM. The frequency and reliability of mainnet forks is unpredictable, so tying major number compatibility to those breaks would result in an unstable release roadmap. For example the "Berlin" hard fork was supposed to either have already been deployed 3 months ago, or it should be in testnets, or it isn't happening until next year, depending on what document you read (ground truth is the last item at the moment).
Dan Middleton
Thanks for writing this up. There's always a balance that projects should be able to do any sensible thing and we should have as much consistency as possible within hyperledger to facilitate collaboration, reuse, and some semblance of coherence (not be the github of blockchains).
Are there specific ethereum community requirements you can link us to?
Have you considered a hybrid scheme to allow you to communicate calendar within semver? If you used the last part of the semver version string as a date would that satisfy Besu's needs?
I also see this https://calver.org/#teradata:
```The library maintainers have crafted a resourceful hybrid of semantic versioning and calendar versioning. The YY.MM part of the version are used as a combined SemVer major version. That is, for new releases, the API of the library remains the same as it did in October 2015. Dependent code written since then is safe to upgrade. We will see the year and month segments update next time there is a breaking API change.```
Danno Ferrin
That is an interesting variant, but since the first two numbers indicate breaking compatibility it is a departure from strict SemVer. They also talked about the confusion that it lead to by keeping the YY.MM since the last breaking change.
I also don't expect us to go 18 months without introducing some sort of incompatibility. If we change the names of CLI flags (blacklist→blocklist) that's a breaking change. If we change our error strategy (https://github.com/hyperledger/besu/pull/1305) that's a breaking change. Arguably any change to the fork definitions of the named networks are all breaking changes.
Arnaud J Le Hors
For what it's worth, I would encourage you to support and document blocklist but still support blacklist so not to break anything unnecessarily, at least as a first step. At least that's what I would expect from an enterprise software where backwards compatibility is paramount, I don't know whether the Ethereum world has different expectations.
Christopher Ferris
It is unclear to me how CalVer helps your situation.
Gari Singh
I'm not quite sure how this helps with the primary issue mentions, but this is an interesting topic.
Why do we even need to have a Release Taxonomy? I understand having release criteria, etc, but do we really need to enforce the same versioning scheme for all projects? I think projects should have a release strategy and version scheme / policy to which they adhere, but seems to me they should be allowed to pick a scheme which works best for the project.
That being said, minimally I agree that we should also allow CalVer as it has gained popularity in the continuous delivery model.
Nathan George
I don’t see a clear reason to oppose CalVer. It is an orderly and rational version number approach, and as long as a project is still actively working to have stability and backwards compatibility, as it makes sense for their user base, it does not seem harmful.