Better document project state

[matthijskooijman]

I think it would be good to update the documentation in this repo, to better reflect the current maintainance status. In particular:

• A little introduction about the maintainance state: Maintained by a team with limited time, focus on bugfixes and received pullrequests.
• Some more information about the development process and policy (as proposed in Repository policies #585) and info for contributors.
• Some information the project history and relation to the rewrite initiative.
• An overview of the repo maintainers and maybe also other related people (distro maintainers, specific testers e.g. for flatpak).
• Information about the release process (and other documentation for maintainers, e.g. how to update flatpak dependencies etc.), as proposed in Document & improve release process #608. Also mention how releases will be announced (only on GH currently, so subscribe to get notified).

I'm wondering a bit on where to put this info. If possible, I'd like to keep the repository root as clean as possible (so I would also like to replace the current AUTHORS and MAINTAINERS files). It would be simple to put all info in the README.

Some of this could maybe go into a CONTRIBUTING.md file, which is also automatically linked by github (e.g. when creating a new issue). Github supports such a file CONTRIBUTING.md in the repo root, a .github folder and the docs folder. As I said, I'd like to keep the root clean, and .github is too hidden for reference docs, so I guess using a docs folder makes sense. We could also add other files there (since CONTRIBUTING.md should be targeted to contributors, but a lot of the above should live elsewhere).

I'm thinking:

• docs/CONTRIBUTING.md with info for contributors. I think the info about development and testing that is currently in README.md can also be moved here.
• docs/MAINTAINANCE.md with info for maintainers.
• README.md for everything else (project status, people and history).

Any other thoughts?

Below some bits of text to include, TBD where exactly.

---

This repository is currently maintained by a couple of people. Since we cannot free up too much time, the focus will be on bugfixes and small improvements. Help is always welcome, we will try to prioritize handling any contributions (i.e. pull requests) that are submitted.

Project history

The hamster project has quite a long history. It was started in 2007 by Toms Bauģis and Patryk
Zawadzki, being called "hamster-applet", a gnome2-specific systray-oriented applet for time tracking. Version numbers followed Gnome versions (e.g. 2.91.3). After a while, the systray applet was replaced by a gnome-shell extension (separately developed at https://github.com/projecthamster/hamster-shell-extension). In 2012 the project was renamed to "Hamster time tracker" and the versioning reset to version 1.x.x. In 2013, the project became largely unmaintained, with some flares of development (mostly porting to gtk3, but this was never released).

In 2014, Markus Koller (@toupeira) took over maintainance of the project and finalized 2.0 release, but then development died down for a while again.

In 2016 Eric Goller (@elbenfreund ) took over the project and started on a complete rewrite of the codebase (see below), leaving the 2.x hamster unmaintained. Development of the rewrite proceeded with ups and downs, but died down again, unfinished, in 2017. Development of the Gnome shell extension continued, but also stopped in 2018.

In 2018, @ederag took over maintainance of the 2.x hamster version again, porting it to python3 and adding various improvements to make it usable again. Somewhere along the way (maybe even before 2.0) the name was simplified to just "Hamster", though "Hamster time tracker" was also used here or there. In 2020, a version 3.0 was released with some significant refactorings and updates of external dependencies. The Gnome shell extension remained without an official maintainer during this period, though a number of people still worked on the project and built on top of each other's forked repositories.

In 2020, shortly after 3.0 was released, maintainance of the 2.x hamster was taken over, spreading the responsibility over a team of four. On the shell extension front, there were more people interested in ongoing development, so a second maintainer team was formed for the shell extension (with some overlap between both teams).

And that is where we stand now.

Hamster rewrite

In 2016, @elbenfreund started a full rewrite of the hamster code (see for example this announcement. This rewrite consisted of a number of different repositories to improve the separation of concerns: hamster-lib, hamster-cli, hamster-gtk and hamster-dbus.

Over the years, development of this rewrite has flared up and died down several times. Currently, this has not yet resulted in a finished and completely usable application.

Until this rewrite is in a more complete state, the original code base (i.e. this repository) is still considered the current version recommended to be used.

[mwilck]

Sounds good to me. I'd place MAINTENANCE.md and CONTRIBUTING.md into the root directory though (and check spelling of "maintenance" 🙂 ).

And we should try to trigger @elbenfreund again to update the information on projecthamster.org. I think he should basically move all those blog entries into some sort of attic or archive, and link to github for up-to-date information.

[DirkHoffmann]

I'm wondering a bit on where to put this info.

In my opinion, unless we have dozens such files, they can stay at root level, where they are most easily found.

[matthijskooijman]

Ok, let's just stick to the root of the repo then. Thanks :-)

I've also started writing some text, editing it in the first post. Feel free to comment or add text already, I'll put things in a pullrequest when it's more complete.

[ederag]

@matthijskooijman

In 2020, shortly after 3.0 was released, @ederag retired as maintainer, leaving the project without a maintainer again. [...]. To prevent development from halting again four people (somewhat reluctantly) volunteered to care for the 3.x version

That's quite a history rewriting.
You came, I left. In this order, not the reverse 🙂.

Here is a neutral text, to replace the whole paragraph:
"""In 2020, shortly after 3.0 was released, a new team took over the wheel""".
(with precisely this phrasing and these links)

[matthijskooijman]

First off: since I have no interest in putting blame at anyone here, so I've updated the text to something more neutral. I liked the original text since it provided some background for the current state, with four somewhat reluctant maintainers that only have time available for basic maintenance, but we can probably get that point across elsewhere and keeping the history overview more neutral seems better. I used a few more words than you proposed and left out the links, since I don't care for adding links everywhere and like to be consistent with the rest of the history section.

You came, I left. In this order, not the reverse slightly_smiling_face.

However, that's not quite how I recall this. Looking back, on March 2nd, you left. The need for new maintainership was not discussed until a full week later on March 9th, with the new maintainers volunteering in followup posts.

I'm not quite interested in discussing this any further, though.

[ederag]

I'm not quite interested in discussing this any further, though.

But still you argued, meddled with the text (which was already a diplomatic offer) and removed the links.
And the essential: you continued to spread misunderstanding, so here are further informations:

---

I was about to continue outside @elbenfreund umbrella,
in a fork becoming the main legacy project,
but then came your lengthy intervention.
Given the reactions to your post (some private), I gave up.

So yes, mostly for this and for other reasons I don't care to discuss about either
(you are not new to this project, and have a special way to be a maintainer),
in my informed opinion, you have a strong responsibility for the current state.
That was about you @matthijskooijman, unless you ask for more.

---

The following other members of the new team were involved
in a collective private e-mail conversation starting on 2020-02-28 (three days before #574)
and are also responsible in very different degrees:
@mwilck for mostly (there were also good sides) FUD, see my warning about ten days before #575,
@elbenfreund for #574 ("gratitude" in words but actual disrespect),
@DirkHoffmann for overstepping his mandate and for a fighty e-mail,
@benjaoming

They were all recipients of an answer to this private conversation, where I asked to

prevent destructive interferences in the repo I'm responsible for.

The only answer to this message was #574, more than 21 hours later.

Let's hope this makes it clearer why your initial version was backwards.

[matthijskooijman]

Thanks for sharing your view on this. I won't respond to it in detail, since I do not think that will bring us anywhere. AFAICS my current proposal for the "history" section does not contradict with your view on things, so I see no reason to change it further. If you disagree, feel free to point out specific things that you think are incorrect and I'll reconsider.