Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 58651 - Bugzilla HOWTO Document for Gentoo Users
Summary: Bugzilla HOWTO Document for Gentoo Users
Status: RESOLVED DUPLICATE of bug 97274
Alias: None
Product: [OLD] Docs-user
Classification: Unclassified
Component: Other (show other bugs)
Hardware: All All
: High normal (vote)
Assignee: Gentoo Infrastructure
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2004-07-28 05:38 UTC by Lance Albertson (RETIRED)
Modified: 2005-07-07 05:05 UTC (History)
9 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments
page-1.html (page-1.html,3.67 KB, text/html)
2004-09-10 04:34 UTC, Gregorio Guidi (RETIRED)
Details
page-2.html (page-2.html,3.76 KB, text/html)
2004-09-10 04:34 UTC, Gregorio Guidi (RETIRED)
Details
page-3.html (page-3.html,4.18 KB, text/html)
2004-09-10 04:35 UTC, Gregorio Guidi (RETIRED)
Details
page-4.html (page-4.html,3.92 KB, text/html)
2004-09-10 04:35 UTC, Gregorio Guidi (RETIRED)
Details
page-5.html (page-5.html,4.33 KB, text/html)
2004-09-10 04:36 UTC, Gregorio Guidi (RETIRED)
Details
page-6.html (page-6.html,5.59 KB, text/html)
2004-09-10 04:36 UTC, Gregorio Guidi (RETIRED)
Details
page-7.html (page-7.html,3.92 KB, text/html)
2004-09-10 04:36 UTC, Gregorio Guidi (RETIRED)
Details
page-8.html (page-8.html,3.83 KB, text/html)
2004-09-10 04:37 UTC, Gregorio Guidi (RETIRED)
Details
Proposed Bugzilla Howto (bugzilla-howto.xml.tgz,1.14 KB, application/x-gtar)
2005-01-08 19:05 UTC, Collins Richey
Details
bugzilla-howto.xml (bugzilla-howto.xml,2.33 KB, text/plain)
2005-01-09 14:42 UTC, Daniel Drake (RETIRED)
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Lance Albertson (RETIRED) gentoo-dev 2004-07-28 05:38:43 UTC
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.
Comment 1 SpanKY gentoo-dev 2004-07-28 06:16:49 UTC
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
Comment 2 Lance Albertson (RETIRED) gentoo-dev 2004-07-28 06:39:13 UTC
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. 
Comment 3 Dylan Carlson (RETIRED) gentoo-dev 2004-07-29 10:43:51 UTC
There's no way to pack all the possible documentation into the "bug wizard", so I think this is important.
Comment 4 Sven Vermeulen (RETIRED) gentoo-dev 2004-07-30 04:31:18 UTC
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).
Comment 5 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:33:57 UTC
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...
Comment 6 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:34:25 UTC
Created attachment 39296 [details]
page-1.html
Comment 7 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:34:51 UTC
Created attachment 39297 [details]
page-2.html
Comment 8 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:35:18 UTC
Created attachment 39298 [details]
page-3.html
Comment 9 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:35:42 UTC
Created attachment 39299 [details]
page-4.html
Comment 10 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:36:05 UTC
Created attachment 39300 [details]
page-5.html
Comment 11 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:36:31 UTC
Created attachment 39301 [details]
page-6.html
Comment 12 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:36:55 UTC
Created attachment 39302 [details]
page-7.html
Comment 13 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-10 04:37:21 UTC
Created attachment 39303 [details]
page-8.html
Comment 14 Lance Albertson (RETIRED) gentoo-dev 2004-09-10 06:49:10 UTC
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!
Comment 15 Jeffrey Forman (RETIRED) gentoo-dev 2004-09-10 07:58:42 UTC
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?
Comment 16 Lance Albertson (RETIRED) gentoo-dev 2004-09-10 08:05:10 UTC
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
Comment 17 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-11 10:28:07 UTC
> 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?
Comment 18 Collins Richey 2004-09-24 16:36:21 UTC
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.
Comment 19 Lance Albertson (RETIRED) gentoo-dev 2004-09-24 19:34:34 UTC
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. 
Comment 20 Collins Richey 2004-09-25 22:51:38 UTC
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?
Comment 21 Collins Richey 2004-09-26 21:01:43 UTC
Never mind about the call for common mistakes, I sent out mail myself.
Comment 22 Collins Richey 2004-09-30 12:45:03 UTC
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.
Comment 23 Gregorio Guidi (RETIRED) gentoo-dev 2004-09-30 16:12:47 UTC
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.
Comment 24 Sven Vermeulen (RETIRED) gentoo-dev 2004-12-02 09:36:03 UTC
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).
Comment 25 Collins Richey 2005-01-08 19:05:35 UTC
Created attachment 47989 [details]
Proposed Bugzilla Howto

Attachment is tar gzipped.
Comment 26 Daniel Drake (RETIRED) gentoo-dev 2005-01-09 14:42:56 UTC
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.
Comment 27 Gregorio Guidi (RETIRED) gentoo-dev 2005-01-11 07:50:34 UTC
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...
Comment 28 Gregorio Guidi (RETIRED) gentoo-dev 2005-02-20 06:12:33 UTC
ramereth: do you think you can take a look at this?
Comment 29 Xavier Neys (RETIRED) gentoo-dev 2005-02-27 10:07:38 UTC
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.
Comment 30 Robin Johnson archtester Gentoo Infrastructure gentoo-dev Security 2005-02-27 16:01:39 UTC
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.
Comment 31 Jonathan Smith (RETIRED) gentoo-dev 2005-04-06 19:15:27 UTC
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
Comment 32 Jonathan Smith (RETIRED) gentoo-dev 2005-04-07 17:00:46 UTC
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
Comment 33 Sean D. Quinn 2005-04-15 17:18:00 UTC
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
Comment 34 Shyam Mani (RETIRED) gentoo-dev 2005-06-25 22:30:30 UTC
Sean, any update on this?
Comment 35 Shyam Mani (RETIRED) gentoo-dev 2005-06-27 23:34:28 UTC
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.
Comment 36 Shyam Mani (RETIRED) gentoo-dev 2005-07-07 05:05:01 UTC
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 ***