determine final versioning strategy about builtin-actors

[anorth]

Thanks for opening this. For background, the approach adopted in specs-actors was an imperfect attempt to live up to semver patterns, since the Go module system enshrines that:

• The major version changed with each new development effort toward a version that would introduce new/changed functionality.
• After a release branch for a major version was cut (toward the end of development, but as soon downstream integration efforts were warranted), the minor version was bumped any time a state schema or request parameter/response type was changed. This indicated that any downstream consumer might have to re-integrate. Because there was no real VM, this pretty well captured changes that could affect gas consumption. (This is imperfect because Go semver says you shouldn't change any interfaces on a minor version bump).
• Within a minor version, we'd bump the patch version for any behaviour changes that emerged during integration testing.
• We initially never used rc or other tags (would use patch instead), but they came in over time.

We don't have to do it that way again, but I wanted to explain the reasoning. This answers your "which events lead to what change" question. As the pace of network upgrades slowed (😢 ) we got "better" at cutting the release branches in more and more complete states, so minor versions were not used much.

Another use case that was more frequent early on is developing and releasing an emergency fix to an already-deployed actors version that uses the same state, but different code. We would bump the minor version number for that (and the code internally would consult the network version as a flag for the new behaviour).

These are all imperfect if one takes the view that versions with any consensus-affecting change are incompatible (i.e. not substitutable with a version-selection algorithm) – which is the case for any logic change even without a real VM. Doing this properly would entail bumping the major version with each tag. We couldn't stomach that since (in Go) the major version change entailed branching the repo, changing all package import paths etc. I don't know enough about Rust modules and imports yet to understand whether this would be easier in Rust. If it is, I'd say we should consider (3) eschew the minor/patch versions entirely, and change the major version with every release, so "smart" requirement selection algorithms can't screw it up. This would mean some actor versions are never activated on mainnet, but skipped.

For (1), I don't really get why changing the patch version is ok while the minor version is abandoned. Using the minor version allows making early tags for integration even while significant development is still happening (e.g. on two independent but significant changes). You might say to use pre-final release tags, but then I think you should take that all the way: (1*) only make pre-final release tags until the release actually goes live on mainnet, and then retro-actively tag the last pre-final release as final. We still then need to solve the "emergency upgrade" case, but perhaps we should just get used to using a new major version for that anyway since the old trick of deploying new code that mimics the live version at network version V, but works differently way at V+1, won't work any more.

So, I think either (1*) or (2) could work, but look forward to more perspectives.

[anorth]

Chatting with @momack2 today, another consideration is the need to pipeline development of different actor versions. When one version is stable and undergoing integration, other developers will often need to be getting started on changes for the next version. This is why release branches in Go specs-actors often had multiple minor version releases before they froze.

This doesn't necessarily constrain version tagging. It'll work with any of the approaches.

[raulk]

Thanks for all your inputs here and for the discussion. It's also very useful to have documented a synthesised version of how specs-actors dealt with versioning.

Here, we have de-facto settled on:

• master being the current, most future actor version in development (by future, I mean the one we believe that will be deployed latest).
• Every time that a development line needs to spin off, create a release/vN (major version) branch.
  • There could be many unreleased development lines in progress at once.
  • This supports the pipelined development approach for higher velocity that @anorth cites.
  • In practice, we should only expect two/three unreleased versions being developed at once. Going beyond that will likely incur in exponential coordination overhead and a complex web of dependencies.
• Releases are made bumping both minor and patch versions, and @anorth's notes above are a good policy tips on when to bump each.