This Time Self-Hosted
dark mode light mode Search

My thoughts about QA and documentation

So, this was discussed today in #gentoo-dev quickly, and I think it make sense to report it here, so at least I can make sure to clear up my own mind writing my thoughts on this matter, always discussed and rarely realised: Quality Assurance.

Let’s start to say that Quality Assurance is a subjective concept. Everybody has a different view of the QA problems, and of the QA process itself. There is who prefers passive QA and who prefers active QA. Different kind of QA process can be used on different kind of projects, and every project should have its own set of QA rules.

There’s no panacea for QA, one cannot simply decide a set of rule and they will be the ones for every project of the world. Things have to be tailored correctly.

What I think of QA in Gentoo is pretty complex. I think we really need a QA team, but how to establish it it’s difficult. There’s no written policy, and in a lot of cases what passes as policy “because it was always done this way” is just a subjective way used by the more vocal part of our developers, that often is the also the older part of our developers, that not always is right.

So, I disagree with trying to enforce QA from day one after establishing rules. We have an example of the past were some developer involved in QA (I try not to say names) asked me personally to convert the || ( .. ) dependency for KDE ebuilds into a range-based dependency … (no comment on this please).

What I think should be done would be to start creating some policies, so that no feature is lost for both developers and users, and that complexity doesn’t make writing ebuild more difficult than it is (not too much at least), and make sure that we accept them for the most part. When there’s disagreement between a developer and QA team, and the developer has reasons (even debatable from the QA team), no one should force the decision until this can be decided. It’s not useful to apply a change that might break stuff for users, and we should think that the maintainer of an ebuild knows it better than anyone in the QA team, as that’s what a maintainer is supposed to do (or we wouldn’t need them, don’t you think that?).

The other big problem is deciding who should make these rules and who should apply them. If it’s the same people it’s likely to be abused on the long term. Tell “the people who wants to join the QA project” doesn’t help, as they might not know our technical limitations either (see above), plus I’ve seen people from all the three package managers that work with ebuilds not understanding how =foo-bar/baz-1.3* worked…

At the end, just screaming “we need more QA” won’t help. Also because QA project should make sure that their rules don’t end up hindering work on any of our current projects, by forcing people on standard tracks that aren’t followed by things like Gentoo/Alt, Hardened or Embedded projects.

On documentation instead, I want to dedicate a single paragraph, that tries to summarise what I said some days ago about the devwiki (that seems to still exist, although I actually forgot about it after last year). I don’t see the usefulness in a private wiki (without public reading) to store documentation. I can understand using it to add reserved information like ports and configuration settings for infra’s servers, but documentation for other projects? Infra is basically the only project that shouldn’t interface with the users, and that has information that shouldn’t be read by them, but for any other project, documentation should be public. You cannot expect users to help, to know the documentation, if they can’t reach them. At the same time, I think just a fraction of our developers have access to the devwiki, and even who has it (like me) might simply forget its existence when they don’t use it for some many months. You cannot look up documentation you don’t know it’s there.

Now to complete my view over the “hot” topics of this Gentoo, I’d like to point to this blog from Clint Adams appeared on Planet Debian and the entry he points to, to let people think about the interminable discussions on our mailing lists.

And now, if the coughs don’t kill me, I’d return to my xine hacking …

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.