Moving Quassel forward

Manuel Nickschas sputnick at quassel-irc.org
Sun Nov 24 16:45:43 CET 2013


On Saturday 23 November 2013 14:32:50 Bas Pape wrote:
Hi Tucos and ML,

> Now mailing lists are finally here after having pestered Sput for
> a while, I figure I actually have to make use of them now too. You may
> or may not have been aware of my umpteenth short hiatus, but this mail
> is not about that. Development on Quassel has been slowing down for a
> while now, despite its considerable, but quiet, userbase (the user
> count in the IRC channel reached 500 recently). Basically the userbase
> outgrew the project, the tracker overflowed and the project is still a
> hobby one (and a young one at that). Here are some thoughts and
> suggestions that would hopefully improve the situation in various
> areas; these are mostly taken from / based on Karl Fogel's "Producing
> Open Source Software" [1].

First of all, thanks for your efforts and thoughts on figuring out how to work 
on fixing the problems we, as a project, most certainly have.

Some background information first before diving into the rest of the mail:

Quassel has basically been a two-man show (EgS and me) up until end of 2009 or 
so, which can clearly be seen in the commit history. Then, real life happened 
to both of us - things like moving from being a student to being employed 
full-time, having a real job in the industry, wasting lots of time on 
commuting, moving places, and so on. Things are calming down for me a little 
bit now that I'm settled in a new place and have a job that I'll hopefully 
keep for a while; on the other hand, I find it really hard to come home after 
a hard day of work and then start being productive in my free time. I guess 
everyone can sympathize with that.

This coincided with a massive influx in new users, which is really cool, but 
also comes with lots of bug reports, feature requests, support requests, and 
the likes. Which are things that further distract from writing code in the few 
and precious hours of free time I can devote to Quassel development. This is 
the main reason I mostly ignored the tracker and partially also the IRC 
channels in the past couple of years.

There's also the issue with the general architecture of Quassel. We made some 
early design decisions, at a time where we didn't foresee having tons of 
users, people writing 3rd party clients such as QuasselDroid and iQuassel, and 
so on, that now come back and bite us. Some parts of the architecture actively 
prevent us from doing some features that are really needed - scripting, file 
transfers, the whole core user management, backlog management and search, 
supporting multiple cores at the same time, and so on.

So behind the scenes, I've been churning along refactoring large parts of the 
code base. Of course, refactorings, while being sorely needed for reasons 
mentioned above, and for lowering the barrier of entry for new contributors,  
generally are not user-visible, and they take lots of time. With the main 
developers being distracted by real-life and investing most of the remaining 
time into behind-the-scenes work, this doesn't help Quassel being recognized 
as an active project.

Now, thankfully we've had a bunch of really helpful users who picked up the 
slack, triaged bugs, turned patches into pull requests, and so on - Tucos 
being one of the most active there. That kind of help is very very much 
appreciated, as without that, the project would've drowned in chaos much 
earlier already.

The move first to Gitorious and later to Github helped very much to get and 
manage contributions. They ease the barrier of entry for new people wanting to 
help; they also make sure that contributions can be easily reviewed and merged 
into the codebase. Most importantly, they make sure that contributions don't 
get lost in a flood of bug reports and requests in the tracker. As a result, 
the past couple of releases of Quassel was mostly user contributions, as can 
also be clearly seen in the commit history. This is very much appreciated, 
too; without users helping out, we couldn't have done releases in a while.

Well, so much for the state of the union. Now onto the things we could 
improve!

> The first thing a user would see is most likely the website. Currently
> it's a somewhat messy Drupal blog with the odd news item, an empty
> Features page, an empty FAQ, links to Redmine and some other stuff.
> The simplest way to improve things here would be to do a rebranding of
> sorts by putting together a clean, simple website. I would suggest the
> following things:
>  - Just have a simple mission statement on the homepage (the current
>    synopsis from the homepage combined with the About page and a
>    screenshot),
>  - Have a seperate news page (if there is an urgent item, put a note on
>    the homepage with a link to the full item),
>  - Features and requirements, just summarize some
>    important features and the necessary dependencies (including those
>    which are optional),
>  - Development status, currently it's still pre-1.0 and slowly being
>    developed, this would also be a good place to show the current scope
>    (more on that later),
>  - No FAQ, if necessary, do it as part of the documentation; ditch the
>    wiki (more on that later too), and a possibly necessary login is an
>    implementation detail that should not be displayed this prominently.

Documentation, the nemesis of every developer, because it takes out even more 
time out of the development budget. But of course, I fully agree that these 
are good, and sorely needed, ideas.

Thing is, personally I'm not good in designing web pages, and obviously I fail 
at keeping them updated and current. So this is a call for help - are there 
any volunteers who would like to undertake such a website redesign, and 
administrate it going forward?

I would like it to still be backed by some sort of CMS, though - I can't give 
out SSH access to our server. I'm perfectly willing to install a framework and 
give out admin access to it to site administrators, though. Doesn't need to be 
Drupal, if people have better suggestions.

Obviously, I can provide content regarding development.

> Secondly a few words on the issue tracker. I personally think Redmine
> works quite well, the issues with Redmine itself mostly stem from
> updating it and upstream maintenance. Switching to something else
> wouldn't be much of a problem, but I think keeping repo integration and
> existing IDs should be a priority.

Redmine has a few fatal flaws, besides it being based on Rails which is a 
nightmare to host. Most prominently, it still lacks captchas and spam control. 
We can't provide anonymous access because of that, and we have thousands of 
dead users in the database who were registered by spambots (but thankfully 
don't actually post spam). And the sole developer of Redmine has been ignoring 
these issues for years; I don't see that improving.

The only alternative I see right now is JIRA, but I still haven't gotten 
around to testing it. We use it at work, and it's a joy to work with as a 
user. It's also really flexible when it comes to designing workflows. And it 
has a Redmine importer - although I am not sure how well that works. This is 
something I need to evaluate soon.

If we were to switch the bug tracking to JIRA, we could also seamlessly 
integrate that with Confluence. Yes, it's a wiki, but one that I would expect 
to be able to be configured in a way that it could hold the main website. It 
would allow us to easily integrate things like roadmaps, open tasks and the 
likes. We run our whole company infrastructure on Confluence and JIRA, and it 
works really well.

Of course, I'm told that hosting that is probably even more annoying than 
hosting Redmine, but at least it's something I want to look into.

>   As for using the tracker, this needs much improvement on the
> dev side. Issues need a quick intake, so that the reporter is still
> interested and knows what he was talking about; either approve it as
> soon as it is reproduced, or ask for more info. Currently there are 422
> open tickets just lingering and lacking consistency in priority,
> category etcetera. 

Yes. You've done tremendous work in triaging things, but we need more 
volunteers who are willing to help with that. It would be my task to get all 
that sorted, but see above - I fail at doing such things.

> This last bit could be improved by having some
> prominently displayed guidelines for filing proper issues. Don't assume
> the user knows what info a developer needs to act upon an issue.

"How to file bugs". Yes, good idea.

>   It should be possible for issues to be filed entirely anonymously
> (e.g. a needinfo issue can just be rejected after 3 weeks lacking a
> response). If a login is a technical necessity (as is the case with
> Redmine), clearly show the anonymous account which can be used.
> Preferably anonymous users would still be able to enter an email
> address for notifications.

Agreed. See above why it doesn't work with Redmine - mostly because there's no 
spam control. This should be easier if we happen to switch to JIRA/Confluence.

> Next up, releases. Currently releases are loosely time-based, mostly
> synced to *buntu releases. This is actually neat, as it means
> somewhat frequent releases, assuming changes were actually available.
> Syncing never should be strict, as hurrying is no good for quality, and
> conversely, reaching the goal early simply means an early release.

I think we've reached a state where we could move away from a release cycle 
synced to Ubuntu. We have this for historical reasons - kubuntu was the first 
major distro to ship Quassel as default IRC client, and back then it was 
important to get major features out to their users before the release window 
closed. Now Quassel has reached a state of maturity (and a slowness of 
development) where it won't harm people very much if they have to wait for a 
few extra months to get them in their distro. There's also PPAs and backports. 
And we've adopted a rigorous versioning policy, where we have clearly 
communicated promises as of what kinds of updates the stable branch sees, 
we're honoring a string freeze to not screw over translations, and thus can 
rather easily get important bugfixes into stable distro releases even outside 
of the release window.

Personally, I'm a huge friend of feature-based releases rather than time-based 
releases anyway, assuming that it won't make us slack again.

>   Usually just before each release, all current pull requests are
> merged. In my view it would be better to merge pulls more frequently,
> this would make progress less intermittent, makes doing the release
> itself less work, and perhaps most importantly it leaves more time for
> testing.

Fully agreed. I have started to change this, and recently merged several 
outstanding PRs. Besides the reasons your stated, it also gives contributors 
not the feeling of being ignored for 6 months.

> One considerable change in how things are coordinated would be
> scoping features. After each release, make a list of things that would
> be nice to have for the next version (if feasible; larger changes might
> need some planning ahead). Don't be too conservative with regards to
> feasibility, things can be descoped again, but it would be nice to have
> an idea of what is going to happen. A nice side effect could be that it
> might give a sense of direction users can influence.

Agreed. A working roadmap would be really nice to have. It also requires to 
put stuff that's being worked on into the tracker, which is a good thing I 
really have to get used to.

> The fourth topic, code, is oddly enough the shortest one; I simply
> don't have much to say that would change things. Ideally every line of
> code that goes into the repository should be reviewed. No comment
> means it's unlikely the review happened, as hardly any patches are
> perfect the first time. I myself hardly ever got comments (only on the
> larger rewrites that are lingering on gitorious), and only a couple got
> a correcting commit directly afterwards. It is important to be
> critical, and - especially for frequent contributors - have the patch
> be resubmitted if something was wrong. Only if it takes too much time to
> go back and forth (e.g. a discussion without a clear direction) should
> the correction be done in their place.

Code reviews are important, which is also something I've learned since I 
started to do professional software development. However, I have a feeling 
that it would be really hard to get reviewers for my own code, in particular 
with the whole architecture rework happening currently, as few people 
understand the code base well enough. I also fail at dumping the vision I have 
in my brain into some real documentation that could be shared and understood.

As for reviews of outside contributions: I always review the code before 
merging. Most of the PRs we got have been of high quality code-wise, so no 
comments required. Sometimes I've just poked the author in IRC instead of 
writing a comment on Github, which is arguably bad because it's not 
documented. I'm not merging code I'm not happy with.

Now, I've been very forgiving (or sloppy) when it comes to things like 
formatting and commit messages. Mostly because I don't want to scare away a 
fresh contributor by nitpicking about whitespace. I've done correcting commits 
for formatting in the past; sometimes I've just let it through even though not 
every whitespace was in the right place. Of course, badly formatted commit 
messages can't be fixed after the fact.

This is in stark contrast to how we handle this at work, where commits are not 
being merged until they're perfect in every respect. Of course, co-workers are 
not volunteers, they're paid to do a good job, so they can get a different 
treatment.

I've been thinking about how I should handle this in Quassel lately, even 
before reading this mail. Maybe nitpicking, if done nicely, isn't that bad? It 
would educate the contributor to not make the same mistakes next time, and pay 
more attention to provide high-quality commits in the future. Updating a PR is 
easy. And the overall quality of the codebase would go up.

"Producing OSS" seems to support that approach. Of course, it requires to 
actually have the guidelines clearly communicated - this would need to be 
another piece of documentation on the new website, right next to "How to 
report bugs". Thankfully, those guidelines don't have to be written by us, 
because we very consciously changed the coding style to that of Qt [1], and 
for commit messages we want to follow the general Git style [2].

I think I will be much more rigorous in the future when it comes to accepting 
these things; hoping that contributors don't feel put off by that.

> The fifth (and last, finally) topic is the most dreaded one,
> documentation. It's most dreaded because it takes a large amount of
> effort, it'll never be finished, and it's not written by its audience.
>   Ditch the wiki, as it simply doesn't work. Getting documentation
> done takes a more centralized effort, which also makes it easier to
> ascertain consistency with regards to style, quality and scope. I think
> a good way to centralize documentation would be to maintain
> documentation in Markdown or a similar format in a git submodule,
> perhaps with some scripting to turn it into a website (or maybe Ikiwiki
> could be used). Even though I am not a fan of it for code, Github's
> online editor and committing would make it simple for users to
> contribute changes to the docs with minimal effort; I think Ikiwiki
> optionally also allows for online editing.

This would mean that users still can contribute to the documentation, which is 
something that we *must* allow. Having it in the repo would also be helpful. 
Now I don't know much about these things and would really appreciate people to 
figure out what would be the best way for maintaining documentation, and maybe 
even volunteer for maintaining the docs going forward.

As a side-note, the Qt project holds all its (exceptionally good) 
documentation in the qdoc format. We would certainly continue to use Doxygen 
instead of qdoc to maintain *code* documentation, as qdoc is way too 
cumbersome to work with; I wonder if Doxygen is as suitable as qdoc for 
creating static and user-facing docs too. If it is, we could generate 
everything in various formats from Doxygen.

Note that we should think if it's possible to create and maintain translations 
of the docs, too! With docs being in the repo, we could maybe leverage 
Transifex for that... however, not sure if it's feasible.

>   Documentation for users should be entirely seperate from
> documentation for developers and both should be clearly indicated. Both
> should be available in the all-on-one-page format and optionally with
> seperate pages. Both should clearly indicate which parts need
> improvement (explicitly asking for contributions), and which parts are
> incomplete or missing (for seperate pages it would be preferable to
> have a non-link in the ToC for missing content, rather than an empty
> page).

Agreed.

>   Documenting planned features in user documentation, possibly
> including UI mockups etcetera, would enable users to chime in early and
> improve the feature before it even gets written. Of course the fact
> that it is planned, but not done, should be very clearly indicated.

Agreed.

>   Lastly user documentation should be included with the release, in
> both plaintext for easy searching and generated for easy browsing.
> Including screenshots could indicate what areas of the UI need
> improvement (which can also be indicated with a request for
> suggestions), besides of course clarifying what button one is talking
> about.

Agreed.

Now the open question is, who is going to write such documentation? We need 
volunteers. When deciding the way we want to store and generate the docs going 
forward, we need to make sure that contributing to them is easy. We need 
people who feel comfortable enough with the project to be able to review and 
maintain the docs.

On the upside, these are tasks that people who are willing to help, but not 
programmers, could help with. We get those every now and then; we "just" need 
to make it easy for them to contribute.

> To conclude this rather lengthy mail, I'd suggest you at least glance
> at interesting sections of "Producing Open Source Software" as it
> tends to make pretty good recommendations. Chapter 8, "Managing
> Volunteers", would be a good read for the Big Boss, as it states some
> not always obvious things contributors often expect. A slightly more
> proactive management would definitely help the project.

Started to read some parts of it; a highly interesting read so far, thanks for 
linking me to it.

Speaking of management - I fail to be a decent project manager (also I would 
like to invest more time into code and less time into managing). This is also 
an area where we could really really use some help. This coincides with 
triaging the tracker, managing tasks, and communicating to users.

That said, I do try to be more active in the channel lately, and to spill some 
of my thoughts there.

Well, these are my thoughts. Thanks for starting up this discussion. Note that 
we don't have many users subscribed to the ML yet; it may be a good idea to 
occasionally link to the archives to get more input.

Have a nice day,
~ Sput

[1] http://qt-project.org/wiki/Qt_Coding_Style
[2] http://git-scm.com/book/ch5-2.html
-- 
Manuel "Sputnick" Nickschas ("Sput" on Freenode)                  |  (o<
Member of the Quassel IRC Project - http://quassel-irc.org        |  //\
Come visit us in #quassel!                                        |  V_/_


More information about the quassel-users mailing list