Awesome: Define a new release strategy (post-4.0)

[Elv13]

First, everything described below is my opinion and not an announcement. I would like feedbacks and other proposals to solve the core issues highlighted by the 4 years delta between our last 2 major releases. The final decision isn't mine to make anyway.

This issue is to discuss how releases will be done going forward. The past 4 years was a total failure in this regard as vast amount of useful code, documentation and bugfix failed to reach 95% of our userbase. There is also the fact that we have been promoting the use of the master branch for a while, but failed to communicate this correctly.

I propose following guidelines to embrace our current practices and make them official

Create one release per commit in the master branch

We already do that anyway. Try awesome --version on the Git master branch and you already see that version number. Also, distribution such as Arch and Debian want the release string to be comparable using >, == and <. This doesn't mean we should officially announce them all. Also, I don't think we should even tag them anymore. We don't have the manpower to keep 2 supported branches.

So, no more 4.0.x releases. just 4.X where X can become very large. Chrome and many other projects already do this.

If it isn't stable and tested, then it doesn't belong in master

The SVN days are long gone, branches are cheap and easy to merge. Most Agile development already follow that rule. We also unofficially follow it. Lets make it official.

Sure, some changes are scarier than other and breakages will happen. Both 3.5.8 and 3.5.9 existed to fix breakages from 3.5.7. If I recall, the same did happen with 3.5.6 and 3.5.1/2. It can't be fully prevented. Lets be cautious, but not overly concerned. Keeping bug fixes away form the releases is often worst than the consequence of the small regressions they can cause. Release early, release often. Even Microsoft now embraced this rule. We're late to the party, lets catch up.

An official tarball release can be generated from the master branch without further process

If there is a bugfix worthy of doing an "official" snapshot release, then merging master into the release branch should automatically generate an official release. The CI could tag it (or not, TBD). A commit or "back merge" should be done in the master branch to keep the commit count aligned. This can be done manually at first (TBD: PGP).

Again, all commits are official releases (see point 1), but to avoid distributions hating us, the official snapshots have to be kept separated from that. We also have to make it clear that those release may contain new features, but that older releases are not supported and we officially don't want backports. This is what Ring.cx (another project I worked on), Firefox, Chrome and other apps do. Debian allow this as long as it is clearly stated, existing feature behavior isn't changed and a maintainer is willing to whitelist the project. Good news, the Debian maintainer with the most(?) of such packages use Awesome.

An API/ABI break will bump the first number

Some breaking changes can be collected into a next branch to avoid pissing off users 42 times per year, but it should be more common than it was in the last 7 years since 3.4 was released. Piling up 2300 commits into a single release for a small project like ours is evil.

This is already a policy for C and C++ libraries enforced by the distributions. (Note that here ABI is application behavior and not binary). Awesome claims to be a window manager frameworks, it's time to behave like one.

Deprecation warnings are kept for a year

Then the next major release remove the code. Having this as an official policy will prevent code rot. Silent deprecation warnings can be promoted to popups in the last X months (TBD)

Define clear guidelines about major release blockers

For 4.0, what got into the release milestone was quite random, including issues 3.5 already had. This need some clarification or we wont ever be able to merge a next branch into master.

Update the "contributor" document to reflect the decision taken

[psychon]

Create one release per commit in the master branch
We already do that anyway. Try awesome --version on the Git master branch and you already see that version number.

A release is more than just a version number. So: No.

If it isn't stable and tested, then it doesn't belong in master

Sure. I didn't know that previously we merged broken stuff. However, on the unstable-side: How many commits did it take until the new widget system worked?

Both 3.5.8 and 3.5.9 existed to fix breakages from 3.5.7. If I recall, the same did happen with 3.5.6 and 3.5.1/2. It can't be fully prevented.

The last sentence is the key point: We continue to do a best effort thing. We cannot guarantee more than that anyway.

An official tarball release can be generated from the master branch without further process

So you want to remove the make dist magic, or what? What makes a tarball official? If it is self-generated, it doesn't sound quite official to me.

And for having releases done by CI: No, thanks.

An API/ABI break will bump the first number

So that means we won't have a v4.1 release, because we break the API all the time?
I like the current state of having a master branch and a 3.5 branch where the 3.5 branch only gets fixes.

I agree that four years are too much, but a new major release four times a year just means that everyone stops using awesome because of too much breakage.

Deprecation warnings are kept for a year

Sure, why not.

Define clear guidelines about major release blockers
For 4.0, what got into the release milestone was quite random, including issues 3.5 already had. This need some clarification or we wont ever be able to merge a next branch into master.

I should have been more clear. I added the milestone (almost) everywhere to make sure nothing gets lost. I also added it to things for which "is it a regression?" was not quite clear. But yeah, I agree that regressions and "big" breakage should be the only blockers.

Update the "contributor" document to reflect the decision taken

Feel free.

I'd also like to have the branches mentioned in there. There must be a stable branch!