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. -- test mailing list test@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/test
