2010-01-11 @ 16:00 UTC (11am EST) - Fedora QA Meeting Recap
jlaska at redhat.com
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:
> 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
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) -
CommonBugs+ (bugs with CommonBugs keyword *and* contain the URL to the
issue on the wiki) -
> 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.)
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.
> 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
> 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:
> 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
> Does that answer your question?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 198 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/test/attachments/20100125/c884a8c1/attachment-0001.bin
More information about the test