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. >
Attachment:
signature.asc
Description: This is a digitally signed message part
-- test mailing list test@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/test
