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_/_