Release strategy

[genaris]

One of hottest topics of today's WG call was about redefining AFJ release strategy in order to make it easier for everyone to work on it. There are some picks I took from the discussion:

1. Let's invert current strategy and put all new features into main, and then back-port (if non-breaking change) to branch of previous major version
2. Let's continue this strategy but release major versions more often (a couple of months or so)
3. Git is crazy. Let's move to the good-old SVN (?)

I was thinking that probably we can do something that is compatible with 1 and 2 (unfortunately, AFJ developers are too young to accept that SVN is the king so I resign from 3) and comfortable for everyone, including framework consumers. These are my thoughts, resulting in an strategy that is mostly a micro-subset of React Native's.

Major version naming

For the time being (0.x.x) we will not be waiting more than a couple of months or a few significant features to release a new major version. This means that going from 0.3.0 to 0.4.0 might not be as significant as going from 0.4.0 to 0.5.0. The only thing that versioning will guarantee is that if you go from a minor version to another (e.g. 0.3.1 to 0.3.3) you will not have any breaking changes in the middle. If you go from 0.3.3 to 0.4.0 it's possible that you'll need to do some adjustments. You'll need to read the CHANGELOG and execute migration scripts (if any).

Branches and releases

main branch will have the latest features and generate an unstable release after each commit. This means that all PRs from contributors will point to it and will not care about breaking changes. Naming of the unstable release will be NEXT_MAJOR_RELEASE.alpha.n where n is an incremental value starting from 0 (e.g. 0.3.0.alpha.0, 0.3.0.alpha.1, etc.), as today.

Once a new major version is about to be released, a new branch from main is created. It is named as the next major version but skipping minor number (e.g. 0.3). Once it's created and CI passes, the very first release of this major version is performed, including the minor number (e.g. 0.3.0). Main branch will then start creating unstable versions named with the next major release (e.g. 0.4.0.alpha.0).

PR management

Now, what happens when new PRs are created? Depending on its nature, different actions would be taken:

• if it's a fix, once merged to main, most likely it will be cherry-picked and put into the current major version (0.3 in previous example). Maintainers must be in charge of picking it, doing the adaptations to make it work (if any) and performing the new minor release (0.3.1).
• if it's a new feature, if it's simple enough or very demanded it might follow the same process than fixes. Also the creator (or anyone) can do their own PR against current major version branch (0.3) to accelerate/enforce this process, provided it does not introduce any breaking changes Otherwise it will be available in next major release (0.4.0) and immediately in unstable release (0.4.0.alpha.x)

Cycle duration

After a certain amount of features/time, a new major release is performed and the cycle starts again, meaning that hopefully there will not exist a need of doing too much cherry-picking/back-porting there. So it will be a single release+maintain cycle that should not last more than 2 months (hopefully much less than that).

The only downside I see is that there will be so much major versions released and that could be confusing, but let's keep in mind that our current major versions are actually minor versions in semantic versioning, so it should not be a big deal.

So what do you guys think about this? Could it be clear and useful for everybody or introduce more headaches and pains than current scheme?

[berendsliedrecht]

I think I agree with basically all you said and I would like to try this after the next major release.

Two notes:

1. I don't think it it such a bad idea to just release "a lot" of major versions, since we are still in 0.X. It makes it a lot easier for us, as we can just release every breaking change as major release (IF we want to). After a 1.0.0 release we might want to slow down, but that should happen automatically because the framework is stable enough for a 1.0.0 release.

2. I think we should also remember that the complete modularization is coming soon. This would make the core so small and rely heavily on separate packages that breaking changes in the core would be very rare. If the AnonCreds Credentials module, or something, would have a breaking change it would not have anything to do with the AnonCreds Proofs module and therefore PRs would not collide. It does not take away that we still have to fix this, but it does tell us that after the whole rework this becomes a way smaller issue.

Thank you very much for the write-up, I think it will also help with new people wanting to know about our release-cycle.

(Maybe we should also add this at the documentation repository as part of like a "new contributors guide").

[JamesKEbert]

Thanks for the writeup @genaris! I really like what you've put together here, but I do agree with what @blu3beri mentioned about having more frequent major releases.
One of my concerns with the porting strategy is that it will make minor non-breaking changes more infrequently released in minor versions, which seem like they should be more frequent than not. That being said, I think having more frequent major releases and clearer non-conflicting branches is a big win.