Skip to content

Commit 97f19b6

Browse files
author
Alexander Hentschel
committed
included Jordan's comment about SemVer being more a hinderance than help
1 parent f491240 commit 97f19b6

File tree

1 file changed

+18
-5
lines changed

1 file changed

+18
-5
lines changed

protocol/20241031-execution-stack-versioning.md

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -306,12 +306,25 @@ behaviour changes are frequently bundled and form a strict chronological sequenc
306306

307307
## Guidelines for Choosing a Component Version Convention
308308

309-
- Use semantic versioning for areas where
310-
- benefit from backwards compatibility outweigh the implementation and complexity cost
311-
- we want to maintain backwards compatability over a longer period of time and across multiple upgrades
312-
- In areas where we can’t easily provide backwards compatibility (e.g. for security or BFT reasons), we should make this explicit by using a single-integer for the Component Version.
309+
- It is recommended that maintainers primarily use Integer Versioning:
310+
Integer versioning is a comparatively simplistic tool. Though it is also extremely general as it makes effectively no assumptions about usage patterns.
311+
Low complexity and its generality are strong reasons for using Integer Versioning.
312+
313+
For Flow, controlling complexity and codifying compatibility is essential. While we have little practical experience, there are strong conceptual arguments that
314+
compatibility expectations, associated risks and additional complexity of more sophisticated versioning schemes may not be beneficial in various areas of core protocol.
315+
Maintainers considering schemes other than Integer Versioning should present _convincing reasoning_ in which areas Integer Versioning falls short for their particular component.
316+
317+
- SemVer may be considered for components:
318+
- The benefit from backwards compatibility outweigh the implementation and complexity cost.
319+
- We are happy to commit to _consistently_ creating software that supports _all_ preceding Component Specification Versions.
320+
Specifically, consider that you are releasing a component specification with version $2.k$, then SemVer makes sense if you can commit that any software
321+
that supports $2.k$ will _also_ support $2.0, 2.1, \ldots, 2.k-1, 2.k$.
322+
- In comparison, we recommend to _not_ use SemVer if you are considering software releases that support only a subset of preceding minor versions,
323+
for example $[2.3, 3.0]$ (but $2.0, 2.1, 2.2$ are not supported). In this case, the software would need to enumerate the supported component versions
324+
explicitly, or know that all minor versions between $2.8$ (lower bound) and $2.13$ (upper bound) are supported (which only works within one major version).
325+
In this case, Integer Versioning is equally useful (for enumerating supported component versions, or providing an interval of supported component versions).
326+
The additional structure of SemVer is more of a hindrance than a help.
313327

314-
:construction: section needs further extension
315328

316329
## Comparison to other approaches in the blockchain industry
317330

0 commit comments

Comments
 (0)