2010-01-11 @ 16:00 UTC (11am EST) - Fedora QA Meeting Recap

[Christopher Beland]

On Tue, 2010-01-12 at 11:13 -0500, James Laska wrote:
> * jlaska to reach out to beland for guidance/ideas on how to document
> the process (or point to existing documentation) for how bugs are
> noted
> (common_bugs, release notes, install guide etc...) How to determine
> which bugs land in which place 

I'm not sure why my name came up, but here's my take on the question:

It's clear that any unintentional "known issues" need to get added to
Common Bugs, and that page is already self-documenting:
 https://fedoraproject.org/wiki/Bugs/Common#My_bug_is_not_listed

There's only one area which might be improved - CommonBugs keyword.  Is
there are particularly good workflow reason why it exists?  Does someone
come through periodically and check to see if all the bugs tagged with
this keyword are actually listed on the wiki page?  Does it motivate
developers to see this keyword?

It would be simpler to say "if you think it's a common bug, add it to
the wiki page, or ask a QA person/list to do it for you if you don't
have permissions".  Then if it isn't on the wiki, it isn't a common bug,
and there's only one list instead of two to maintain and no
synchronization necessary.  (In this streamlined cases,
frequently-encountered bugs could be marked e.g. F12Target or given a
higher severity, for tracking purposes.)

If we want to keep it, adding a link to the Common Bugs page that does a
Bugzilla search for all open CommonBugs in the appropriate Fedora
version would be a good idea.


The Release Notes are maintained by the Docs Project, which I'm not a
primary participant in.  Their wikispace is a mess; there are a lot of
obsolete pages that need to be cleared out, and current information that
needs to be more cleanly organized.  The release notes are pretty
clearly the place for announcements about changes, and they get written
mostly from scratch each cycle.  

https://fedoraproject.org/wiki/How_To_Contribute_to_the_Release_Notes
lists "Six Ways of Submitting Content" which seems a bit crazy.  I've
not had much success (I think this was between alpha and beta) using the
"Beats" process in the wiki, which are supposed to be rolled into
release notes.  I would really expect to see one page in the wiki
somewhere that represents what the Fedora 13 release notes are going to
look like, but right now there's just stuff from Fedora 12 marked as
"this is final and has been sent for translation".  What's actually *in*
the Fedora 12 release notes is similar, but clearly a lot of editing has
happened between the time it was taken from the wiki and the time it was
released.  I'm also not confident that methods that involve sending a
message to a mailing list are reliable; Bugzilla reports are much better
at persisting until someone actually deals with them.

There are actually three release note issues in any given release cycle
- alpha, beta, and final - each of which to me should build smoothly off
the previous issue (adding new notes and deleting obsolete ones).  It
seems like in an ideal world, these would just live in the wiki, and at
the appropriate times in the schedule, get translated and rendered into
HTML or XML for publication on the web and in RPMs.  Right now, I'm not
confident that anything I put in the wiki would get added to the release
notes, so I just file reports in Bugzilla and let the Docs team deal.
This also seems to be the only way to change release notes after they've
been finalized.  Which might not be a bad thing, since you think there
should be a high bar to changes at that point, but if that's the best
route, it's probably best that the documentation reflect that.

All of the other guides (Installation, SELinux, Deployment, etc. at
http://docs.fedoraproject.org/) also seem to live in a version control
system off-wiki, which if you ask me tends to create a bottleneck and
discourage random people (like community QA participants) from
contributing.  A wiki, after all, is just a version control system that
manages formatted text in a very user-friendly way.  When documents are
off-wiki, that also encourages the growth of redundant content in-wiki,
which attracts attention and  updates, further starving the off-wiki
version of contributions.  I suppose if the content must remain off-wiki
for whatever reason, this could be avoided by squashing these redundant
documents and leaving placeholders admonishing potential contributors to
file bug reports against the off-wiki documentation instead.

It seems right that bugs aren't mentioned in the guides or release
notes, as that helps reduce clutter and centralize fast-changing
information.  Major bugs are fixed before release, and minor bugs are
documented online in Common Bugs or Bugzilla, since the status of fixes
and workarounds is dynamic.  If the slow-changing documents all link to
Common Bugs, that should work pretty well, unless you think people
without network should have access to "known issues" in their copy of
the distribution.  That could be fixed by including a snapshot of
"Common Bugs" in the fedora-release-notes RPM.  There doesn't seem to be
much point in updating it after the release except for re-spins (which
are unofficial).  If you don't have network access, the original version
is accurate because you haven't gotten any updates.  If you do have
network access, you should get the online version, and so the RPM
version would need to have a line at the top that says "This page was
generated on [date]; for the latest known issues, workarounds, and
fixes, please see [url]."

Our guide for bug-filers:
https://fedoraproject.org/wiki/Bugs_and_feature_requests
doesn't encourage them to contribute to Common Bugs or the Release
Notes, though it links to both.  In a document aimed at first-time or
second-time Bugzilla users, that might be for the best, especially if
the contribution process for each of those areas is documented
internally.

Does that answer your question?

-B.