search

projecthamster / hamster-shell-extension

Shell extension for hamster
http://projecthamster.org
GNU General Public License v3.0
214 stars 91 forks source link

Support & release paths for old and future Gnome Shell #319

Open benjaoming opened 4 years ago

benjaoming commented 4 years ago

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:

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:

Goals

Versioning scheme

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

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:

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago
  • 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
DirkHoffmann commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago
  • 3.26 OpenSUSE 15.1 (deprecated?)

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

benjaoming commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

3.36: Ubuntu 20.04 LTS

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

benjaoming commented 4 years ago

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 commented 4 years ago

The official e.g.o extension comes under the contact@projecthamster.org 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 commented 4 years ago

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 commented 4 years ago

@DirkHoffmann sure thing

benjaoming commented 4 years ago

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 commented 4 years ago

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:

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

Suggestion

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:

EOG

Distros

benjaoming commented 4 years ago

@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 commented 4 years ago

(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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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.
mwilck commented 4 years ago

@benjaoming, it would work either way, I don't mind.

elbenfreund commented 4 years ago

@benjaoming @mwilck I prefer (1) As it makes the temporary nature of such "maintenance release branches" clearer. After all, at some point, we will drop support for those old shell versions and can remove the branch, right?

mwilck commented 4 years ago

@elbenfreund, I'd suggested (1) but as I said, I wouldn't mind (2), either.

I would vote against removing branches though. That would take away the option for volunteers to fork that branch and maintain compatibility for old versions. When we drop support, we could add a README saying saying "this branch is frozen and unmaintained" in a final commit, and/or possibly rename the branch to reflect its unmaintained status in some way, rather than delete it.

elbenfreund commented 4 years ago

That would take away the option for volunteers to fork that branch and maintain compatibility for old versions.

Thats a valid use case. I suppose you can not "fork" a ?

benjaoming commented 4 years ago

Indeed @mwilck , a release branch should not be deleted, ~as that would permanently remove stuff that isn't merged anywhere else~ -- which would be sad. Edited: Tags ensure that a reference exists.

By following a strict naming scheme, the release branches won't clutter any views. Can be for instance release/1.0.x and release/1.1.x.

elbenfreund commented 4 years ago

Indeed @mwilck , a release branch cannot be deleted, as that would permanently remove stuff that isn't merged anywhere else -- which would be sad.

Are you sure about that? I just did a simplistic PoC on my local machine, and I can still access a tags history after removing the original branch.

mwilck commented 4 years ago

Are you sure about that? I just did a simplistic PoC on my local machine, and I can still access a tags history after removing the original branch.

Fair enough, but why would you want to do that?

elbenfreund commented 4 years ago

Fair enough, but why would you want to do that?

I understood @benjaoming comment:

Indeed @mwilck , a release branch cannot be deleted, as that would permanently remove stuff that isn't merged anywhere else -- which would be sad.

as, if he fears we would look the "legacy maintenance" backports if we remove the release branch once we no longer want to support the old shell version. That seems to be not the case. As far as I understand, the whole reason for the branch is, so we can add commits (which of cause will trigger new "bugfix release" versions, which means tags). Once this need stops, there seems to be no benefit to keeping the branches around. The history (up to that point) would be preserved by release tags.

mwilck commented 4 years ago

As you like. It's not going to happen any time soon, will it?

elbenfreund commented 4 years ago

It's not going to happen any time soon, will it?

I have honestly no idea about how many past shell version will need to be maintained in parallel. But just to avoid misunderstandings: At the end of the day, you pick what works for you :) I feel that we are on the same page on the big issues, so I am far from interfering with your work.

The issue of binding our self to shell version names by naming our minor releases the same is a far bigger risk/issue in my book.

benjaoming commented 4 years ago

@elbenfreund you are right that the tag will remain, so sure thing, you could potentially delete a release branch at some point.

What was the point again? That at some point there would be too many release branches? Sure, maybe, I never tried it. Do you have this experience?

elbenfreund commented 4 years ago

What was the point again? That at some point there would be too many release branches? Sure, maybe, I never tried it. Do you have this experience?

hehe. I guess its about semantics: in my model, branches are for doing things, tags are for referening a fixed status.

It depends, If we only create release branches when we need them for a separate "backport branch" I doubt this is much of an practical issue. If we create a "release branch" for every release, I feel we are generating noise and miss out on one of the exact use cases tags are good with.

benjaoming commented 4 years ago

branches are for doing things

Would it work, if we say that a release branch is to accommodate those things that are done for old releases?

I mean, if you don't have it, either contributors will think it's not possible to target changes for old releases, or they will have to target the wrong branch and then spend precious time writing about whether or not to have a branch for a patch release.

rhertzog commented 3 years ago

I have skimmed through the discussion but I would not have expected so much discussion on this topic. I'm fine with the proposals. But most shell extensions that I have seen just have a single branch that's supposed to work with the latest GNOME release (while trying to keep backwards compat to some level) and when you get something that works for the given release you put out a tag corresponding to the GNOME release (eg GNOME_3.36).

You tell users of very old GNOME releases to fetch the tarball from those tags and users of recent GNOME versions to fetch the latest regular release.

I believe we don't need much more than that. But to properly close this I suppose that we should document the release/maintenance workflow in some README.contributors or similar.