RFC: Release policy

[BANOnotIT]

Recent release of @reatom/eslint-plugin and future release of @reatom/form package showed that current release and version policy have some pain points. In this proposal I'm trying to cover current release and versioning policy, state its strengths and pitfalls, try to find why it was chosen. After that, I propose new policy that tries to fix pain points while keeping some of the original decisions that led to the current one.

Current policy: One Major Platform release

As discussed in the chat (ru) current major release policy gives developers implicit understanding on what works with what. It also reduces burden of maintaining all correct dependency ranges, that also simplifies install process and increases DX.

Also, currently there's vague LTS policy on all major releases that historically represent architectural approach on reactive system and ecosystem that can be built around such reactive system. The next major platform release will take advantage of implicit context and new API that'll be incompatible with v3.

But the platform is not fully settled yet. New entities, new approaches, and new integrations are being developed and tested. While some of them (such as @reatom/form) are developed in-house and not available for public yet, some developments (such as reatomResource from @reatom/async) were implemented in public and tested using main distribution channel. The latter was considered experimental, and I personally was involved in testing it in real product, but it was released as a public API that everyone can use. We still have reatomAsyncReaction as a tombstone of release-everything-immediately approach.

This whole system was working okay when Artyom was the most active developer and was in control of development of every package in the platform. But reatom gets more people interested in community. We have paid and unpaid volunteers that are willing to implement new features and some of that features may require breaking public API.

Positives:

• One platform-wide major release is easier for developers to understand
• It's easier to maintain
• Basically all major releases are considered LTS just because they are major
• It's easy to explain and promote to newcomers

Negatives:

• The whole ecosystem is hard tied to the platform major version and limits new developments
• When the ecosystem needs to release a breaking change, we either
  • are forced to state it in docs (e.g. @reatom/form), or
  • come up with some shenanigan to trick npm's resolving system without marking major release as major (@reatom/eslint-plugin v3.5.0 and yet to come v3.6.0 that fixes resolution for ^3.0.0 requirements)
• No stated experimental API policy

New policy

I propose to state several mechanics that embrace npm's dependency on SemVer while keeping the major release as a statement:

• LTS bundle
• Experimental features track
• Out of band major releases

LTS Bundle and keep-up major bumps

• LTS Bundle is a set of packages and versions that are considered stable to work with each other.
• LTS Bundle is explicitly marked as such and all packages that are part of LTS Bundle have the same major release number.
• The major release number is the next major release of the bigger of the packages included in LTS bundle.

Tip

Let's say we have @reatom/core@3, @reatom/eslint-plugin@4, and @reatom/form@4.
We want all of them to be in next LTS release.
In that case the release will have major version of 5 for all packages.
That means that @reatom/core v4 will never be released.

Experimental features track

Features that are in active development should be released using experimental SemVer prereleases and npm's experimental version tag. Experimental features should be fully developed, have full documentation and clear use cases to be deemed stable.

Tip

Let's say we want to introduce new API in @reatom/npm-react.
And right now it's version is 8.3.1.

We do new feature and release it's experiment with npm version tag "experimental" and version 8.4.0-rc.0.
If we find something useful to add or change we release next experimental with the same tag but with different prerelease: 8.4.0-rc.1.

When feature seems to be stable, clear and fully developed we release new version 8.4.0 using "latest" npm tag.

Out of band major releases

We can state that we allow unbound major releases with the following conditions:

• These are used only if backward compatible version is not possible or feasible to develop
• That new major release is fully compatible with packages of previous LTS bundle packages

You can drop deprecated APIs in new major releases.

Tip

We want to introduce new @reatom/npm-react version that is not fully compatible with previous v3.8.1.
So we create v4.0.0, but since previous LTS is v3 we are forced to support all LTS users.

New policy conclusion

Proposed policy enables reatom developers to do experiments with public API without breaking with existing npm ecosystem while still providing API consumers to operate with platform major release numbers and getting LTS goodies.

Positives:

• The whole ecosystem uses SemVer compatible policy that plays well with npm
• API consumers still can communicate using major release numbers
• Reatom developers can have public experimental features

Negatives:

• The "release new LTS" process become harder and requires more paperwork
• We introduce some maintenance burden for reatom developers when dealing out of band major releases, yet these releases are not common
• Platform releases will now have "gaps" in versions because of keep-up bumps

If you have any comments, please write it here or state in the chat.

[artalar]

Looks nice!

[artalar]

@BANOnotIT sound very objective! Will you add this in the docs? Im ready to apply a PR.