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

Mon Jan 25 15:54:37 UTC 2010

On Mon, 2010-01-25 at 01:00 -0500, Christopher Beland wrote:
> 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:

I took an action item a while back to pick your brain.  Adam & I were
interested in your take as to whether there were any improvements to be
made in detailing how we document 'issues' during a release.

> 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?  

Here's the workflow I've been following:

While testing, if I come across an issue that, for whatever reason,
indicates the need for a documentation change, I was unclear as to where
the change should take place.  My understanding of how this works ...

     1. If the issue discovered also highlights a larger behavioral
        change that should be referenced in the release notes.  In this
        case, a bug should be filed against the release-notes component
        in bugzilla?
     2. It may change the steps in a procedure outlined in one of the
        official Fedora documents (see http://docs.fedoraproject.org).
        Again, file a bug against the specific document in bugzilla.
     3. Or, the issue doesn't warrant a change to any documented
        procedures, but is of sufficient visibility, list the issue on
        the CommonBugs page.

Does that accurately reflect how to address how to document issues?

> Does someone
> come through periodically and check to see if all the bugs tagged with
> this keyword are actually listed on the wiki page?  

Yeah, during F-11 and F-12, there were a lot of CommonBugs at different
stages in the release.  I personally was using 2 queries to keep an eye
on where things stand with CommonBugs.

CommonBugs? (bugs with CommonBugs keyword, but do not yet have the URL
to the CommonBugs wiki) -
https://bugzilla.redhat.com/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=CommonBugs%3F&sharer_id=141215

CommonBugs+ (bugs with CommonBugs keyword *and* contain the URL to the
issue on the wiki) -
https://bugzilla.redhat.com/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=CommonBugs%2B&sharer_id=141215

> Does it motivate developers to see this keyword?

Uncertain.

> 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.)

So this would remove entirely the need for the keyword?  As you noted,
the 2 methods for updating content on Common_Bugs wiki are:

     1. Add the issue to the wiki yourself
     2. Request that someone from the QA team document the issue

The CommonBugs keyword comes into play for #2

> 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.

Agreed, there are several handy queries around CommonBugs.

> 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.  

I don't hear a lot of complaints about that now, and I think it's
reasonable to have live information require network access to retrieve
it.  But should this become a big issue, the solution you identify seems
reasonable.

> 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).  

Adam can say more here, but I believe updates do happen after the
release.  For example, if a day-0 or later package update resolves an
issue on the Common_F#_Bugs page, the wiki is updated to direct users to
the applicable bodhi update.

> 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. 
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/test/attachments/20100125/c884a8c1/attachment-0001.bin 