Support & release paths for old and future Gnome Shell

[benjaoming]

On the encouragement of @DirkHoffmann, I'm opening this issue with a proposal of how we can maintain our Gnome Shell extension given a history of challenges with supporting various Gnome Shell versions. Currently, they are:

• 3.26 OpenSUSE 15.1
• 3.28: Ubuntu 18.04 LTS, RedHat EL 7
• 3.30: Debian Buster
• 3.32: Fedora 30
• 3.34: Debian Bullseye/Testing / OpenSUSE tumbleweed / Fedora 31
• 3.36: Ubuntu 20.04 LTS

The major problem seems to be this: Users/everyone are confused about which gnome-shell version is supported, developers are disagreeing about how to maintain support for various gnome-shell versions in the same git/release branch.

We want to both develop the extension, and we also want to keep supporting old stuff, but we can't do both, see for instance the convenience.js issue.

There's a longer elaboration coming up, but here is what my suggestion would boil down to:

• We use semver (semantic versioning)
• Release series (x.y.*) are tracked in separate git branches according to decisions about which gnome-shell the release series supports
• Every time support for a gnome-shell release is dropped, a new release series is created.

Goals

• To maintain a functional release of hamster-shell-extension that works with the latest hamster (currently 3.0)
• To merge bug fixes for older versions of Gnome shell which:
  • Maintains compatibility with the latest hamster release
  • Fixes security aspect
  • Other obvious bug fixes

Versioning scheme

Looking at packaged Gnome Shell extensions for Debian There are 4 different versioning schemes in play:

• Date / git hash-based: So basically the least semantic/complicated choice.
• Incremental major version: Some projects seem to have gone very unsemantic and are already at very high release numbers.
• Gnome shell version: Some projects use for instance 3.28.x-nn to denote which Gnome shell they are compatible with, hence just one at a time.
• Normal semver (semantic versioning) of Major.Minor.Patch, 1.2.3.

I would propose normal semver, coupled with a release note template.

Major: Reserved for major rewrites Minor: Changes to gnome-shell compatibility, new features, deprecation of older hamster/gnome-shell releases Patch: Bug fixes, additions to upstream Hamster support.

Here's an example with three fantasy releases: 1.0.2 adds a fix for 3.28 (for a new Hamster release) and 1.2.1 is a patch release with a bug fix for the previous 1.2.0. 1.3.0 is a new release that removes support for an older gnome shell (and bumps the minor digit).

Note that 1.3.0 should merge or cherry-pick the bug fix from 1.2.1 because it affects a supported Gnome Shell.

## 1.3.0 - 2020-03-03

* Gnome shell support: 3.32, 3.34, 3.36
* Adds 3.36 support
* Removes 3.30 support

## 1.0.2 - 2020-03-02

* Gnome shell support: 3.28
* Adds support for Hamster 3.0 #123

## 1.2.1 - 2020-03-02

* Gnome shell support: 3.30, 3.32, 3.34
* Fixes screen lock bug in 3.34 support

Git structure

I'd propose branches for each release:

• master contains unreleased changes for the latest upcoming release. Unstable/beta/rc may be released from master. It could for instance be tracking an upcoming 1.2.0 release -- but as soon as it's released in a stable way, a new release branch is created and tagged. This is also a great place to temporarily support odd-numbered (unstalble) gnome-shell series in preparation of their stable versions.
• release-1.1.x contains both upcoming unreleased changes and previous releases in the 1.1 series. Is tagged with each stable 1.1.x release. Many new PRs should be opened on this, as it's the latest stable release branch.
• release-1.0.x contains both upcoming unreleased changes and previous releases of the 1.0.x series. New 1.0.x releases may be created and tagged here. If something is changed, it should be merged to release-1.1.x -- but not at all costs (see below).

Objective - but not a guarantee: It would be great if release branches could be merged cleanly into newer ones. This way, it can be easy to introduce a bug fix in an older release series and merge it forwards. But this can break for various reasons, and cherry-picking changes backwards or forwards might be necessary.

Where will stuff be released?

First here in the upstream repository. Then packages will be made by other package maintainers. So very conventional.

I would like to start supporting a Debian release for this extension, and I can see that it's done before with many shell extensions. For various reasons, maintaining a separate Linux packages is necessary and decisions about release management and version schemes have to hold up long term.

I would like to develop this in a separate repository, hamster-debian. And I already know that @ matthijskooijman might be interested :)

Next steps

Do people agree that this can be a way forward?

Related

https://github.com/projecthamster/hamster-shell-extension/issues/304

[edit 1: added addition known Linux distribution gnome shell versions] [edit 2: "For various reasons, maintaining a separate Linux packages is necessary and decisions about release management and version schemes have to hold up long term."]

[benjaoming]

None of this is intended to stall current work with merging PRs, but the ones that cannot be merged (because they address older support) might be left for later and be retargeted to different git branches.

[mwilck]

@benjaoming, whoa, extensive work!

I agree with your branching approach, but I have my doubts wrt the versioning. First and foremost, there has been almost no "new feature" development in the extension for years. I actually tend to think that this is a good thing. I consider the extension pretty much feature-complete, and (like for hamster itself) I believe we should strictly avoid creeping featurism bloating the current lean UI. That's of course debatable. But as long as we don't change much feature-wise, I see little reason to change the current 0.1.0 version number, except perhaps the last digit.

Anyway, do we need to express GNOME shell compatibility in versioning at all? Extensions.gnome.org doesn't need that, because it has separate fields to indicate GNOME shell compatibility. The same applies IMO to distro packaging - distro packagers know what GNOME shell version the distro ships, and can arrange for package dependencies to make sure updates are smooth. That's much better anyway than updating GNOME and finding 80% of installed extensions to be non-functional (AFAICS there's no automatism for updating extensions installed from e.g.o.).

Objective - but not a guarantee: It would be great if release branches could be merged cleanly into newer ones.

ACK in general, but the way things have worked lately, I don't think this is going to happen. We're more likely to commit to the master branch and cherry-pick, and given that most of the development is related to GNOME compatibility anyway, I see no big issue with that.

For various reasons, I think that extensions.gnome.org is a mess, and maintaining a separate Debian package is the easy, solid and long term solution.

Full ack for openSUSE. This is what I did for the hamster extension.

[mwilck]

Btw, GNOME will introduce a new tool for extension management. I've no idea yet what this means for extension maintainers (or if it means anything, actually), but history has taught me to expect no fun.

[benjaoming]

@mwilck ACK back :) I also see that this extension isn't doing much more than to maintain compatibility with Hamster and gnome-shell, and not much else activity can be expected for now. The "new feature" thing also would happen in minor versions, whereas major versions are for theoretical rewrites (let's say the no fun gnome extension tool becomes necessary).

Is there anything in the proposed semver that you would want adjusted? I want to propose the "Next steps", but I just really want people to voice any big concerns before this is done.

[DirkHoffmann]

• 3.26 OpenSUSE 15.1 (deprecated?)
• 3.28: Ubuntu 18.04 LTS
• 3.30: Debian Buster
• 3.34: Debian Bullseye/Testing / OpenSUSE tumbleweed / Fedora 31
• 3.36: Ubuntu 20.04 LTS

• 3.28: + RedHat EL 7
• 3.32: Fedora 30

[DirkHoffmann]

@mwilck wrote:

@benjaoming wrote:

For various reasons, I think that extensions.gnome.org is a mess, and maintaining a separate Debian package is the easy, solid and long term solution.

Full ack for openSUSE. This is what I did for the hamster extension.

I would like to pull this specific question out of this issue, if you don't mind: #320.

[mwilck]

Is there anything in the proposed semver that you would want adjusted?

Hm. Our "major" version is currently 0, and I see no justification to bump it to anything else anytime soon. The only official release so far, "0.10.0", supports GNOME up to 3.28. So yes, we could use the "minor number" to indicate GNOME version compatibility. Perhaps we should make it a bit easier to identify by using "0.30.0" to indicate GNOME 3.30 support, and so forth (we can't use 0.3.30.0 or 0.3_30.0, because it would be below 0.10.0 for most standard versioning schemes).

So, I guess I'm ok with the general scheme you proposed, but I believe we have a looong way to go until we fill that complex scheme with real code.

[mwilck]

• 3.26 OpenSUSE 15.1 (deprecated?)

Not yet. We have also SLE 15-SP1, which will remain supported for several years.

[benjaoming]

Our "major" version is currently 0, and I see no justification to bump it to anything else

This is not a proposition, I used 1.x.y examples, sorry if that was confusing.

[benjaoming]

I would like to pull this specific question out of this issue, if you don't mind:

Someone, somewhere at some point are gonna be affected by decisions of release management and versioning schemes. But of course who/where/when isn't up to this issue -- it's just acknowledging that extensions.gnome.org isn't sufficient. I'll remove my subjective comment immediately :)

[mwilck]

I agree with your semver proposal.

My proposal for next steps: Once #316 or something similar gets merged, I'd propose to tag the result as "0.32.0" (using the minimum supported GNOME3 minor version as minor number). A possible release for 3.22 - 3.30, based on an earlier commit, e.g. 66a717d, might be tagged "0.22.0".

Does that make sense?

[benjaoming]

Added additional distribution info, thanks @DirkHoffmann and @mwilck - I hope this overview will be useful. I imagine some kind of support matrix (table) in the README that makes it clear which release branch to target (as a developer), and which release to use (as a user).

[benjaoming]

@mwilck it makes sense, we could do that!

I never tried this scenario before: But say we release 0.32.0, could we then later (because it's lower priority and maybe takes more time to finish) release 0.22.0 ? The whole interval between 0.10-0.32 would be free.. but just kind of unconventional to pop in a 0.22 later? :) I think we could do it, nonetheless and then find out if it's a bad idea later in life :)

[mwilck]

But say we release 0.32.0, could we then later (because it's lower priority and maybe takes more time to finish) release 0.22.0

I see no problem with that. It makes perfect sense (in your scheme, actually) that the version number for a newer GNOME release would be higher than for older releases, and I think users understand that "higher version" does not imply "later release".

Anyway, it's just a proposition. I guess @elbenfreund will have a say, too. It was he who tagged the 0.10.0 release, as part of his intended move to the new hamster-lib design which hasn't happened so far; so the major version "0" actually expresses the alpha status of the hamster-lib code base at the time he created the tag. Which begs the question whether we need a version relationship between hamster itself and its extension. For openSUSE I decided against that. I currently use these versions:

hamster-time-tracker-2.2.2
gnome-shell-extension-hamster-time-tracker-0.10.0_3.34

(note the additional _3.34).

On openSUSE (I guess, every rpm-based distribution), version-scheme changes are a pain in the neck, in particular if the new version appears to be lower than the previous version. The "epoch", which can be prepended to the version, is deprecated. All you can do is change the package name, and that has already happened a few times for hamster. I'm running out of good options for the package name. So, I really hope that we're not moving towards a hamster 0.x release, even if hamster-lib gains momentum again.

[mwilck]

3.36: Ubuntu 20.04 LTS

Do we have any information whether our 3.34 code works with 3.36?

[benjaoming]

It's my understanding that @elbenfreund has yielded control of the repository but not extensions.gnome.org -- however, he said that he would release things that got tagged here. So I hope that our decision here is fine, but also that someone eventually can take over the permissions for releasing on e.g.o.

[mwilck]

The official e.g.o extension comes under the [email protected] UUID which (I suppose) is owned by @elbenfreund. So it would really be up to him to upload other versions, unless he wants to redirect that email address to somewhere else (e.g. the hamster-dev mailing list).

[DirkHoffmann]

Added additional distribution info, thanks @DirkHoffmann and @mwilck - I hope this overview will be useful. I imagine some kind of support matrix (table) in the README that makes it clear which release branch to target (as a developer), and which release to use (as a user).

I like to keep READMEs short (otherwise they become TLDRs). MATRIX.md or SUPPORT-MATRIX.md would be my favourite. Or VERSIONS.md (in spite of ambiguity with HISTORY.md)?

[benjaoming]

@DirkHoffmann sure thing

[benjaoming]

There are a lot of things going on right now, so in a couple of days, I'll get back with a proposal for "Next steps".

[elbenfreund]

First of all, thank you all for your great writeups and careful considerations in this issue so far. A lot of content went into this already and my reply is bound to miss some of the points raised above. Please feel free to point out missing answers and shortcommings. The following is simply meant as my perspective and how I envisioned versioning at the time (and mostly still do).

Versioning

1. SemVer :+1: Absolutely! In addition / contrary? to @benjaoming s suggestion about the semantics I would stick with the dogma of:

• major release: API breaking (that means API for extension users!) changes (I do not see that happening anytime soon.
• minor: added feature (that includes supporting or dropping new shell versions)
• patch: hot- and security fixes

I would be a bit unsure about whether dropping support for a given hamster-dbus API would trigger a major or minor release.

It was/is a deliberate choice to:

• decouple our versioning from gnome-shell versions (and hamster-dbus API)
• the major 0 was meant for the time of the extension rewrite, to indicate its unstable API while allowing me to publish intermediate results fast so ppl could still use it. If you feel confident about the upcoming release, I suspect we could and should start with 1.0.0.
• EGO uses a simplistic "build number" versioning internally with just an ever increasing integer. There is no way to meaningfully map our versioning to this anyway. But this seem an implementation detail of the specific release. But it is one of the reason why I feel it is important that users have an easy way to "show extension version" (as in our version).

Branches

I think @benjaoming suggestions a well thought through and sensible. However, I would propose a slighly different approach. I would be curious about your opinions:

Premise / Assumtions

• The extension is pretty much feature complete
• We want to minimize maintenance effort and add new features only to the "latests" version
• Support for older versions, that are "required to support" because we want to enable users of those shell versions, can be limited to "patch releases" (as above). That is hot/securityfixes.
• Support for old versions is time limited and will cease as soon as the shell version that juststifies their existence stops being relevant to us

Suggestion

• master is just a shortcut for "latest stable release"
• develop is the result of latest stable release + `` all merged PRs towards the next release
• development happens on feature banches and is merged via PRs
• each release is "tagged" with (tag name == version name)

That covers the simple straight forward development workflow, but does not account for shell versions dropped along the way that we may still want to support. Whenever we are about to release a new version that drops support for a shell version (that we still want to support), the following is done on top of the steps above:

• a new legacy release branch is created, branching of the latest stable version that still supports the "old shell version".
• any relevant fixes from current and future development that needs to be merged will be cherry picked on this branch.
• This branch can be versioned using tags just like above, as it will be limited to patch releases. (this can not interfere with current development versions because they will have a higher minor version).
• Once we drop support for this particular shell version, we remove the branch (the tags still stay around).

EOG

• Each release results in us building a extension artefact ready to be installed.
• We provided this as an asset on GH
• We upload this to EOG, triggering their review process

Distros

• Any kind of distro integration should be out of scope of our own release efforts and happen in a dedicated repository. either under the projecthamster umbrella or on the distros own infrastructure.

[benjaoming]

@elbenfreund

I don't really have the time to take this any further. I agree with your presumptions.

From experience, I would discourage having master and develop. You get the extra hassle of sync'ing stable stuff into master (which is often missed) and frequently having to explain people the difference between the two and to re-target. Instead, you can just ensure that released stuff is always put into its own release branch, and then the master (or if want, call the default branch develop) will always just be the latest development version.. so if you release 1.1, the master should become 1.2.dev in the same go.

I would also be cautious of feature branches, they create a mess in the upstream repo that is left for others to clean up (which takes a lot of time "what is this, where is it going, is it yours?"). People should develop in their own branches on their own repos however they want -- and open PRs (now there's a draft option on Github) to get feedback.

Am fine about bumping to 1.0.x - I have no opinions, but you skipped @mwilck 's suggestion to use the minor version:

My proposal for next steps: Once #316 or something similar gets merged, I'd propose to tag the result as "0.32.0" (using the minimum supported GNOME3 minor version as minor number). A possible release for 3.22 - 3.30, based on an earlier commit, e.g. 66a717d, might be tagged "0.22.0".

[matthijskooijman]

(edit: I wrote this before reading the previous two comments, but I think everything still applies)

I'm a bit late to the party, but I have some comments (just some observations, overall the plan seems perfect).

Objective - but not a guarantee: It would be great if release branches could be merged cleanly into newer ones. This way, it can be easy to introduce a bug fix in an older release series and merge it forwards. But this can break for various reasons, and cherry-picking changes backwards or forwards might be necessary

In practice, I think that us developers might be running newer versions of gnome-shell rather than older, so it seems likely that a fix is first introduced into master or one of the latest release branches and then ported backward, rather than forward. But it should not matter so much which way we port fixes, of course.

perhaps we should make it a bit easier to identify by using "0.30.0" to indicate GNOME 3.30 support, and so forth

This sounds good and clear.

I wonder if we need some consistency about the "feature" level of all branches as well? E.g., I could imagine that we use the revision version number to indicate what bugfixes or features a particular branch has received. For example, say we have a 0.30.3 version, then release 0.36.3 from master to support shell 3.36 (and drop everything below). We'd keep the revision the same to indicate that these are essentially the same versions, except for the supported shell version. If we would then fix a bug in 0.36.4, backporting that bugfix would result in 0.30.4, making it directly clear that these are again the same versions, with differen shell support. We might also have an even older 0.22.3 version, which has not received the bugfix yet for lack of testing, but that is directly visible from its minor number.

This scheme would run into problems when some fixes or features cannot or need not be backported, where the consistency would break down (and you'd have to resort to one more version digit, e.g. 0.30.4.1 to fix something gnome-shell 3.30-specific), so it might not be so ideal.

Thinking about it, the problem I'm trying to solve is to make it clear which versions have which feature/fix level, and this might just be a matter of proper documentation in the changelog (e.g. under version 0.30.x say "This backports all fixes up to 0.36.y").

Also, in this scheme, do we even need a master branch? Even the master branch has a minimum supported gnome-shell version, so it could just be a release branch for consistency?

Minor: Changes to gnome-shell compatibility, new features, deprecation of older hamster/gnome-shell releases

With @mwilck's proposal to use the minor version equal to the gnome-shell version, this does mean the minor version can only be changed when we drop older gnome-shell releases, no longer any of the other reasons above. I think this is fine, just something to realize.

Also, I wondered why we actually need to change the minor revision when dropping shell versions. It made sense intuitively, but thinking about it a bit more, I see that bumping the minor version actually frees up the previous minor version for more bugfix releases for that older gnome-shell version. E.g. if we would have 0.30.1 and release 0.30.2 without support for 3.30, then there's no more room in the version scheme to release a fix for 3.30 (other than 0.30.1.1, but well).

Finally, wrt to compatibility, I hope that this is mostly an issue on the gnome-shell side, where the interface changes often and in undocumented ways, which makes it hard to properly support a large range of shell versions. On the hamster side, I would expect less frequent changes and more attention to compatibility, so in general, I think the shell extension should support a wide range of hamster versions, so it's ok to not track this so explicitly (e.g. not reflect it in the version number).

[mwilck]

@elbenfreund,

* minor: added feature (that includes supporting or dropping new shell versions)

[...] It was/is a deliberate choice to:

* decouple our versioning from gnome-shell versions (and hamster-dbus API)

I don't understand. Do you want the minor number to reflect GNOME shell compatibility, or not?

[mwilck]

From experience, I would discourage having master and develop. [...] Instead, you can just ensure that released stuff is always put into its own release branch

Ack. Actually, I'd go one step further and say that no branch is needed as long as the release doesn't require bug fixes. A tag would be sufficient.

[elbenfreund]

I don't understand. Do you want the minor number to reflect GNOME shell compatibility, or not?

I expressed this badly. A droped or added shell version leads to a new minor release, as it adds functionality. The version name however is not relate to the shell version.

[benjaoming]

With @mwilck's proposal to use the minor version equal to the gnome-shell version, this does mean the minor version can only be changed when we drop older gnome-shell releases, no longer any of the other reasons above. I think this is fine, just something to realize.

In this way, we only need to bump the minor release version when shell version support is removed. We always have the freedom to add more support in a patch release.

@mwilck

I'd go one step further and say that no branch is needed

The intention of release branches is to be able to maintain older releases without the deprecation/removal frictions that are created from merging everything into the same branch. Being able to backport and do old patch releases is important.

[elbenfreund]

From experience, I would discourage having master and develop. tl;dr: :+1:

I share those experiences, but thought people "expect" a master branch. If this works for you, just having a develop branch without the hassle of a "derived" master is preferable to me. "The latests stable release" can easily reference by a dedicated (moving) tag if one wants that...

I would also be cautious of feature branches

:+1: I phrased that very badly. your description is perfectly fine with me.

I'd propose to tag the result as "0.32.0" (using the minimum supported GNOME3 minor version as minor number).

As said before, I feel that we do ourself a disservice if we tie our versioning to the shell verison name. BUT: how about having an additional git tag (like shell-3.30) that gets attacked to the latests release that still supports said version?

The intention of release branches is to be able to maintain older releases without the deprecation/removal frictions that are created from merging everything into the same branch. Being able to backport and do old patch releases is important.

But such a need for a dedicated "release branch" would only arise if the following two conditions are meet, right?

1. Develop drops support for a given shell version
2. The dropped shell version is one we aim to keep supporting

[mwilck]

@benjaoming

The intention of release branches is to be able to maintain older releases without the deprecation/removal frictions that are created from merging everything into the same branch. Being able to backport and do old patch releases is important.

Sure. I only wanted to say that the branch is only needed when such backports become necessary.

[benjaoming]

Sure. I only wanted to say that the branch is only needed when such backports become necessary.

Yes, well, two ways:

1. Create it on-demand: The option to target a previously unpatched release is only available to repository admins. Every release branch will require a communication "does anyone mind that I just create a new release branch?"
2. Create it immediately and by protocol: Risks creating a release branch that never receives commits.