Versioning and Release Cadence Plans

[akosthekiss]

I think that now that version 2.0 of JerryScript is out, we (as the maintainers/reviewers of the project) may acknowledge that our release strategy has been suboptimal. The project wasn't dead, as it was being continuously enhanced and extended. Yet, there had been no release for a period of almost 3 years. Yikes!

So, I propose to adopt two concepts from now on (i.e., should this motion pass):

• "Release early, release often" (*)
• Semantic versioning

(* With the remark that "early" shouldn't and mustn't mean "buggy".)

So, a bit more thoughts about these ideas:

Release Cadence

For v2.0, we wanted to give our community a nice well-polished set of new features, APIs, etc. I don't think that we've failed, but it just took too long.

So, I propose to release a new version whenever a reasonable new feature or feature set is landed and stabilized in the project, even if we know that there will be related features implemented in the near (or not so near) future. Same goes for bug fixes and refactorings: even if the project is not extended feature-wise for some time but some useful internal refactorings or fixes are landed, we should come out with a new release.

I'd encourage all contributors to be pro-active. If they land some features in the project and think that it forms a nice "package" of improvement of the project, they should raise their voice and advocate a new release. (Maintainers should still have the final word about releases, but this could ensure that a release potential will not slip their attention.) A GitHub Issue seems to be a good way of proposing a new release, it will allow discussion between interested parties.

Should a motion for a new release pass, we'll have to ensure that it is in a reasonably stable state. CIs should be green. Known bugs should be fixed (as much as reasonably possible, at the discretion of the maintainers). Landing of features should be frozen for a short period to focus on stabilizing the release. (This should be some days or a week or so, when no new bugs pop up. This may depend on the volume of changes, but I'd prefer no overly long freezes. Just enough to make sure that we have a good level of confidence in the stability of the project.)

Some notes:

• This is NOT intended to mean a release after every commit. Of course not.
• No strict periodicity. We may have some months between some releases (e.g., if heavier features are being implemented), but we may also have days or weeks between some releases (e.g., if we only land fixes, or smaller features).
• Contributors may still open PRs and get reviews (modulo reviewers' availability) while the project is "frozen" before a new release.
• GitHub Milestones might be used to track work left, once we have agreed on the necessity of a new release.

Semantic Versioning

I really think that this would fit very well to the above-suggested frequent release strategy. We got some annoying bugs fixed: great, let's have a release x.y.Z+1! We have support for a new ES6 language keyword, or some new builtins got implemented: great, let's have a release x.Y+1.0! We have reworked the API: ok, let's have a major version bump. (Now, that shouldn't happen too often. But we shouldn't be overly afraid of it either. The right balance is the key.)

Some notes:

• We could say that we're already using semver. But actually, we aren't. We'd at least require a patch version number. (This also means that if/when we add the patch version macro to our headers, thereby we extend our API, so our next release will be version 2.1.0 right away.)
• We'll have to state clearly what constitutes our public API that falls under the jurisdiction of semver. (E.g., IMO, binary snapshots MUST NOT be considered as part of the public API. They are not for persistent storage between versions or between devices. A bump in the snapshot version SHOULD NOT imply a major version bump of the project.)
• To state the obvious: adding a new public API function does not require increasing the major version, it only bumps the minor one.
• We shouldn't be afraid of major version bumps, but it shouldn't happen on daily basis either. It has to be the maintainers' responsibility to have some foresight and plan breaking changes carefully. We have to offer some kind of API stability. (Foresight and planning also imply some kind of a feature roadmap. We'll have to have a (separate) discussion about that, too.)
• This wouldn't mean the maintenance of multiple major version or LTS branches, backporting bugfixes, etc. I don't think that we have the resources for that. Versions (that follow semver) remain tags on the master branch.
• We might also introduce a tag named "latest", which should always be moved to the latest release. (A good practice used by other projects out there.) (But this should be the only tag moving. Semver tags MUST stick.)

Looking forward to comments.