Moving Quassel forward
baspape at gmail.com
Mon Nov 25 20:30:46 CET 2013
First off, I think I may have been a bit too specific with regards to
my recommendations; I don't care much for how things are implemented,
especially as I won't touch most things anyway. What matters currently
is getting an idea of which things need to be done and how to run the
project on a higher level. Of course it'd be swell if you feel like
picking up something immediately, but but then it'd be best to discuss
that topic in detail seperately.
On 2013-11-24 16:45:43 +0100 Manuel Nickschas wrote:
> On Saturday 23 November 2013 14:32:50 Bas Pape wrote:
> > The first thing a user would see is most likely the website.
> 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.
Documentation and the website are rather distinct topics. The website
would mostly be a one-off rework and be low maintenance (depending one
the level of automation for roadmap and such, but again, details).
> 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's not that I despise wiki's in general so much that I won't consume
any content hosted by something similar to a wiki. The "ditch the wiki"
recommendation was intentionally under documentation, I'll explain
that in a bit more detail, as more people thought that was odd.
> 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.
Hosting is entirely your own party, you may inflict as much pain on
yourself as you feel like.
> Yes. You've done tremendous work in triaging things, but we need more
> volunteers who are willing to help with that.
I've hardly ever properly triaged bugs. The only thing I did was close
duplicates and mark things as solved.
> 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.
Normally I would agree, but currently that last part is a problem,
which is why I like loosely time-based releases. Assume a couple of
bugfixes and one feature some people like are the only things
available; with a feature-based release, these would linger until more
things accumulated; with a time-based release, they'd at least be made
available at some point.
> 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.
Of course, it was mostly aimed at contributions; although it'd be
desirable for every commit to be reviewed, that's simply not possible
> Now, I've been very forgiving (or sloppy) when it comes to things like
> formatting and commit messages. [..]
> 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
Disagree, being paid means they don't have the choice to not do it, as
well as not always getting to pick what to work on and when to do so.
Contributors shouldn't be treated much differently, lenience with
regards to time is expected, but not with regards to quality.
> 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.
Exactly my point. If people bother to contribute patches, they most
likely also care about quality. If they are regulars, they are expected
to adhere to style and quality standards.
> 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.
Just make sure to ask, rather than tell. If one can decline without
fuzz, you might just have to do it yourself once a blue moon, but I
doubt contributors would actually be annoyed by this.
> > 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.
The reason I recommended to ditch the wiki is because it's an
exceptionally freeform medium and everything added goes into
"production" immediately. This would mean that in order to ensure
quality, the wiki would have to be monitored actively.
On IRC it was suggested a centralized effort could be done using a wiki
too, but this would mostly mean just laying down some guides to denote
areas that need work and perhaps limit scope to some extent. I highly
doubt that such an approach would get things done and maintain
consistency. Next to that, it would complicate getting plaintext docs
and formatted docs for offline use (i.e. in the package).
> 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.
I personally dislike in-code documentation, even though they are
closely related. For API docs it makes some sense (more so if it's
actually documenting a public API), but the mess it yields just puts me
off (I know folding helps, but still..). Besides that minor point, API
documentation is only a small part of docs contributors need; as they
are editing the code, the API is in their editor already, a higher
level overview and the way things work together is much more helpful.
> 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.
I realized this too when someone mentioned it on IRC. I'm having a
hard time to think of a way to do this in a way that would not make it
an utter pain for translators to keep up with the source language;
might be worth looking at how others do that.
> Now the open question is, who is going to write such documentation? We need
> volunteers. [..]
> 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.
I don't expect much problems getting a handful of contributors for docs
once a proper infrastructure and trajectory are available. It'd be nice
if some would-be contributors would speak up before you settle on
> 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.
The tough life of the BDFL, especially if he doesn't have poor lads
to appoint managerial positions.
> That said, I do try to be more active in the channel lately, and to spill some
> of my thoughts there.
That's probably the second-best way to show you're alive.
-- Bas Pape (Tucos)
More information about the quassel-users