Release process recommendations

[diwakergupta]

Starting this thread to gather potential improvements to the release process. As we get alignment on specific tasks, we can turn them into issues for tracking.

I've based the recommendations below based on feedback from integrators, exchanges; from surveying how other projects (Polkadot, NEAR, Algorand etc) handle releases and from my own experience and observations.

Please add your ideas as comments!

• Release priority: The release text, changelog entry and announcement email should all indicate a release priority -- that is, how important is it for someone to upgrade to a given release. We could use a scale like High / Medium / Low; or Critical / Moderate / Optional or something similar. Basically anyone running stacks-node (either as miner or follower) should clearly understand if they need to upgrade ASAP or can delay for a scheduled maintenance or can skip (optional upgrade).
• Release cadence: Outside of hotfixes for critical vulnerabilities, we should establish a release cadence for important update. For instance, we could aim to do a monthly release from now until 6-8 months after Stacks 2.1. Alternatively we could use some other marker for "stability" -- like we can maintain this cadence until we get to a point where for 3 subsequent months we have nothing new to ship. Just some ideas; the key is to create some predictability for node operators.
• Release candidates: If we establish a cadence, we can also establish a corresponding cadence & process for "release candidates". For instance, we can publish a "pre-release" which we deploy to the testnet for at least a week, before promoting that to an actual mainnet release.

[diwakergupta]

• Better/automatic Changelog: if we adopt and require conventional commits, we could then add automation to generate and maintain a changelog, and in future, add additional release automation around it.

[CharlieC3]

+1 on conventional commits. Integrating that with this project would be a door to more automation with new releases, and also a unique opportunity for this project to align with Semantic Versioning standards -- to which aside from the versioning scheme, it currently does not.

This project adopts the SemVer versioning scheme of MAJOR.MINOR.PATCH, but the way each placeholder is currently treated during a release does not follow SemVer guidelines. Releases for this project have fallen into a versioning pattern which resembles the following:

• Never increment the MAJOR version
• Increment the MINOR version on hard forks
• Increment the PATCH version on everything else

This pattern has the potential to create confusion in the developer community because the versioning scheme appears to follow Semantic Versioning through the format, but doesn't because of the above versioning pattern. Most developers would stop investigating our release process as soon as they see the SemVer format of 2.0.9 and look no further. So on critical upgrades like a hardfork to 2.1.0, most developers may upgrade thinking reverse-compatible features were added but instead it was much more.

I would suggest the project's versioning pattern changes to align more closely to SemVer guidelines where:

• Backward-incompatible changes like hardforks increment the MAJOR version
• Backwards-compatible features increment the MINOR version
• compatible bug fixes increment the PATCH version

That being said, it doesn't seem like many blockchain projects follow Semantic Versioning, so there may be some functional reason not to that I may not know about, but in a developer-first community I'd think this change would make sense.

[kantai]

I would be supportive of conventional commits only if we also required "squash and merge" to merge PRs -- that gives us the chance to automate change logs, and it makes the git history much more reflective of the actual changes occurring, which in turn makes the source code easier for new participants to get up to speed on.

The reason I think this needs to be squash and merge is that almost every PR on this repository goes through a multi-round feedback loop. This in turn means many commits, most of which make no sense as a conventional commit. Theoretically, the PR authors could squash/rebase in their PRs, but that makes reviewing very hard, because you can't refer back to issues raised in a review to see whether or not they were resolved without rereading the whole patchset.

[CharlieC3]

@kantai There's an option we can enable for a protected branch like develop where linear history is required, effectively disabling "merge" commits for that particular branch. There's no inverse of the rule though, so we can't require only "merge" commits just for one particular branch like master. So half of what you want could be enforced, we'd just have to remember to do a regular "merge" commit from develop into master to maintain the commit messages.

[kantai]

Hmm -- I'm not sure how this would impact the develop -> master and master -> develop merges, but I'm ultimately more concerned about enforcing this on feature PRs and hotfix PRs.

[CharlieC3]

Regarding release candidates, the first RC was published from the develop branch. It may be helpful to auto-create a new RC for each commit/merge into the develop branch.

We also have the next branch for hardforks like 2.1.0, but as others have mentioned in Discord, this branch may be too difficult to automate for RCs at this time. For now the suggested approach here is to create a new RC off the next branch through the stacks-blockchain GH workflow.

[CharlieC3]

Would anyone want to change our versioning scheme from N.N.N to the more traditional vN.N.N?

The reason I ask is because:

• version numbers which follow semantic-versioning are usually prefixed with a v to denote what the string represents
• some of the automatic versioning tools expect this signifier to determine the previous version released. I've already experienced some difficulties helping automate the stacks-wallet versioning because of irregular version formats.

There are ways to circumnavigate this in the tooling, so it can come down to just a matter of preference. I'd like to know others thoughts despite this though.