After following a thread on the -dev ML, I came to the conclusion that Gentoo was missing proper documention to guide a user through our bugzilla system. We currently have a document for creating ebuilds with do's and don'ts, and I think we should create something similiar for bugzilla. It was noted in the thread on -dev that users repeatly will assign bugs improperly without knowing the proper usage. I propose we create a document for users, and eventually one for developers. I would work on this, but I don't know a lot of the dos and don'ts other developers have.
i thought that was the point of the guided bug entry system ? even with that, some users still dont correctly use it, so creating another document somewhere wont make a lick of a difference i dont think
Yes, the guided bug entry system is a good system, but a lot of our users like having a document to read from our main page. This document could point out things that may not be possible in the bug entry howto.
There's no way to pack all the possible documentation into the "bug wizard", so I think this is important.
How extended should the documentation be? I was more thinking along the lines of a single chapter (at most one and a half screen long) with points and initial instructions, added to the current support page (http://www.gentoo.org/main/en/support.xml).
The flaw of incoming bugs is really overwhelming. With the current pace, by the end of the year Gentoo will have 10.000 open bugs, and this means that each developer will have hundreds of bugs that he doesn't even know of, nullifying the purpose of tracking bugs with bugzilla. So we need to close more bugs, but how? experiment with human cloning and produce ten copies each of eradicator, mholzer, vapier, _mr_bones? run the ciaranm script to close all bugs as WONTFIX? Seriously now, I think this howto is a good idea if it can make the quality of incoming bugs a bit higher. But I think that we also need to stop more bugs from the 'pick a product' page to the 'enter bug' page, adding more infos there. I propose to make the process that goes from the 'Enter bug' link to the enter bug form a bit longer (three or four clicks) and usable, to have time to give some basic informations. I'm attaching 8 hand made html pages to show the concept, take a look and say what you think...
Created attachment 39296 [details] page-1.html
Created attachment 39297 [details] page-2.html
Created attachment 39298 [details] page-3.html
Created attachment 39299 [details] page-4.html
Created attachment 39300 [details] page-5.html
Created attachment 39301 [details] page-6.html
Created attachment 39302 [details] page-7.html
Created attachment 39303 [details] page-8.html
Wow! Thanks for contributing that! I'll have to take a closer look at it, but its at least a start. Jeff: I'm adding you since you're the new bugs admin along with me, so I'd like to hear your comments on this!
I see there are different html pages, would those be made into a completely seperate document, or would those go on the appropriate bug entry pages? I think having a seperate self-sustaining document would help, but honestly, I wouldn't take the time to a bug-submitting howto, I'm impatient and head strong like the rest of us. I would have no problems hacking the source of bugzilla to maybe add descriptions on the filing pages though. Lance, thoughts?
I was thinking more of creating a document that would reside on www.gentoo.org and then have the step by step stuff that we already have in place [1] updated to reflect that doc on our site. When people want to look for docs, they generally look for it on www.gentoo.org. We can easily link this doc on the bugs opening page somewhere for new people. But a single page for a doc for www.gentoo.org was more in line with what I was looking for. [1] http://bugs.gentoo.org/enter_bug.cgi?product=Gentoo%20Linux&format=guided
> I see there are different html pages, would those be made into a completely > seperate document, or would those go on the appropriate bug entry pages? The html pages are meant to be hacked into bugzilla source, that's just my proposal in parallel to the bugzilla howto document (the content could be shared, naturally). Moreover, I would like to point your attention to this sentence in the bugzilla guided form: Please note that all bugs should be submitted here first before being moved upstream. I don't think that currently Gentoo has the manpower to comply with that directive (actually 20-30% of reported bugs are upstream bugs). I would like to see a discussion about changing this policy (send all bugs to us and we will send them upstream), that is currently applied only in rare cases, with a softer one (if you don't know if a bug is Gentoo's fault, send us, but you could be invited to send it upstream). What do you think?
I am not a developer, but I will be happy to make a first cut at producing a Gentoo Bugzilla HOWTO. I have the Gentoo documentation DTDs, xslt stuff, etc. on my PC, so I can view the correct results before submitting it. I will simply supply you with a valid *.xml document as an attachment to this bug, and then we can discuss changes, approval, etc. What I propose to do is 1. Introduction 2. A tour of the main page of the bugs.gentoo.org site 3. A tour of the guided format to reporting a bug 4. ???? If you have any suggestions, or if someone else is already working this document, let me know.
I'd probably add a section about common mistakes sorta like the ebuild doc. We might need feedback from the developers/community for that to be effective. I could write up an email and send it to the -dev mailing list to get feedback on that section.
Yes, please do issue a call for common mistakes. Another question. The new and improved Guided Format pages that Gregorio prepared look very good to me. Should I base my document on these or on the current Guided Format?
Never mind about the call for common mistakes, I sent out mail myself.
Re: comments #13 and #17 - the new proposed pages for Bugzilla. These pages are very good, but I have a problem with Page 8 (compiler problems). IMO, the link Submit the bug should direct the user to the Guided Format not the Expert Format. All of the recommendations in the Guided Format (checking for dupes, etc.) are still applicable for this type of problem.
Thanks for the feedback! You're right, the link should be to the guided format. There are also other little issues: for instance I used 'Subject' instead of 'Summary'. Naturally the pages are meant to be expanded (the post from pauldv on gentoo-dev had a lot of useful suggestion), and hopefully reworded by some native english speaker.
Infra monkeys, are the mentioned pages good enough for inclusion on the bugs.gentoo.org website? Richey, I think it's the easiest to base them on the new pages (makes it future proof).
Created attachment 47989 [details] Proposed Bugzilla Howto Attachment is tar gzipped.
Created attachment 48055 [details] bugzilla-howto.xml Here's the plain text version (the only file in the tgz). I asked Collins to post this here.
I thought I could use my brand new web space, so I'm reproposing the idea of changing the aspect of the 'Enter Bug' page, hoping that it could raise the quality of incoming bugs. Here's how it might look like: http://dev.gentoo.org/~greg_g/enter_bug/enter_bug-main.html It can be improved in many ways, but it's a start. What's your opinion? Is it possible to know from infra guys if this is technically feasible? In case it is, I can ask for more feedback on gentoo-dev...
ramereth: do you think you can take a look at this?
Could we fix the following issues related to docs? As far as docs are concerned, a very common mistake is docs-team being assigned bugs it can't do anything about. It's natural for users to assume all documentation issues should go to the docs-team and they should be told otherwise. docs-team only cares for pages under /doc/ and translations. Anything else is handled by the corresponding project (/proj/) or infra. docs-team can't do anything about man pages either. The current split docs-user/docs-developers is useless as bugs end up assigned to docs-team anyway. Besides the component list is outdated. Could we have the following items instead: . Gentoo Documentation: Handbook and guides under the /doc directory and any translation. Component list could be as simple as Handbook, Any Guide, Translation, Other. Those bugs get assigned to docs-team. . Specific Documentation: Project documentation (under /proj), man pages, other.
one comment reading the above could you please inform users that the best way to search for previous bugs on a package is to prefix their simple queries with 'ALL', so that they see the closed bugs as well, and not just see that there is no open bug, and proceed to open a new one.
the xml page on this bug is rather blank. would anyone be interested if i redid it and included a much expanded list of common pitfalls when submitting bugs (such as assigning all docs to doc-team, "emerge -e world fails", and so on) if so, i can have it in a few days time
swift says to wait until bugzilla modifications are complete, but might i might write a doc and keep it in here (IE: not publish) until the bugzilla mods are completed
I'm going to considerably work on this, and I'll take as much authority as I can by working on the guide and combining some of the attachments here. -SDQ
Sean, any update on this?
Could you chaps take a look at Bug #97274 and add comments/suggestions if any? This bug's been open for ages, and Chris has written up a really neat what to report & how to do the same. Any suggestions would be welcome, and we could push that one in if we're fine with it.
Since no one had any issues, I'm closing this one as a dup of the newer bug. The bugzilla-howto will be up at http://www.gentoo.org/doc/en/bugzilla-howto.xml in a wee bit. Thanks! *** This bug has been marked as a duplicate of 97274 ***
