Mailing List Archive

Hi Chris,

Chris White wrote:
> Doc is still here:
>
> http://www.gentoo.org/doc/en/bugzilla-howto.xml

I've just read over it in full. It looks good - thanks for writing it.

As you know, I've been meaning to write one of these for a while. I've been
keeping a list of topics I think should be mentioned. Stripping out the ones
you have covered, here's what I have left:

maintainer-needed description
maintainer-wanted description
why isnt my bug being looked at
why isnt my ebuild being looked at
what are bug-wranglers
never reassign a bug
dont close as fixed just because you have a workaround
if in doubt, let the developer close it
link to how to go into the testing tree
make sure you are using the latest version
always try the testing package before reporting bug
dont pollute existing bugs by posting unrelated or related problems. use one
bug for one issue.
always post "emerge info"
always upload as plain text
always attach large postings, never paste
always use unified diff
always post stuff on the bug, never in private email unless requested
if you find a duplicate bug, instead of filing yours, tag onto the end of the
existing one, even if the information you are adding does not differ
debugging with dmesg
never say "it doesnt work" or "it crashes"
post config.log if it fails during configure
why did you mark it as upstream instead of fixing it yourself
how to apply patches in general
how to apply patches in ebuilds

Since the doc is already covering a lot of content, and adding some of these
points to it will broaden it further, I think it makes sense to have 2 docs.
One for "how to report a bug", and another for "how to give us lots of yummy
info" in a bug report.

Something like:

How to report a bug:
- Search, check that nobody has filed it already
- Fill in the form under the right product
- How to get "emerge info" output
- General policy stuff:
- If attaching, use plain text and never tarballs
- Don't reassign bugs, leave that to devs
- Don't close just because you have workarounds
- What to do if your bug isnt getting attention
- maintainer-needed/wanted description
etc....

How to give us lots of yummy info:
- How to apply patches
- How to use strace
- How to identify a configure failure
- and how to upload config.log
- How to use gdb, for C apps
- Using valgrind?
etc....

That way, most users will find all the information they need in the first doc,
without being scared away by scary stuff. It would also serve as a document
that you can read and understand in full before filing your first bug. Those
who have the time and experience can go onto the second doc and learn how to
help us debug the problem after the bug has been filed.

It could also be used as a reference thing, e.g. on a kernel bug, I'll say
"please try this patch", user says "how?", it would be nice if i could point
them to a specific page on the tech doc.

Daniel
--
gentoo-dev@gentoo.org mailing list

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Chris White wrote:
> Doc is still here:
>
> http://www.gentoo.org/doc/en/bugzilla-howto.xml
>
> After a good ammount of user input the bugzilla doc has been updated. The new version uses ggdb3 instead of g for debugging and contains a new section on testing ebuilds. Thanks goes to robbat2 for his commentary on what to improve. Thanks goes to the people who help fix my crap for grammar mistakes ;). So far it seems to be comming along nicely, I've been notified of the upgrade to bugzilla comming soon, and will update my screenshots and other information accordingly. Thanks again to everyone.
>
> Chris White

This sort of thing could reduce the number of INVALID and NEEDINFO bugs.
Great job!

Nathan


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFC0TvG2QTTR4CNEQARAl3LAKCd4ODRkgSLpgf64yz1BcrGZAbnAwCeKPg+
RNBnuP0w+ISiDU2XFvqU3js=
=c30Y
-----END PGP SIGNATURE-----
--
gentoo-dev@gentoo.org mailing list

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 07/10/2005 08:27 PM, Daniel Drake wrote:

> As you know, I've been meaning to write one of these for a while. I've been
> keeping a list of topics I think should be mentioned. Stripping out the ones
> you have covered, here's what I have left:
>
> maintainer-needed description
> maintainer-wanted description

These two are there, but kinda obscure. They need to be more prominent.
As for the rest of the points you've brought up, did you have time to
pen down answers as well? If so, could we have a look at them please?
Some answers are obvious, but some others aren't and these points are
quite valid and do need to be in the doc.

> Since the doc is already covering a lot of content, and adding some of these
> points to it will broaden it further, I think it makes sense to have 2 docs.
> One for "how to report a bug", and another for "how to give us lots of yummy
> info" in a bug report.
>
> Something like:
>
> How to report a bug:
> - Search, check that nobody has filed it already
> - Fill in the form under the right product
> - How to get "emerge info" output
> - General policy stuff:
> - If attaching, use plain text and never tarballs
> - Don't reassign bugs, leave that to devs
> - Don't close just because you have workarounds
> - What to do if your bug isnt getting attention
> - maintainer-needed/wanted description
> etc....
>
> How to give us lots of yummy info:
> - How to apply patches
> - How to use strace
> - How to identify a configure failure
> - and how to upload config.log
> - How to use gdb, for C apps
> - Using valgrind?
> etc....

Yeah, I guess that's the way the doc will go now. I'll have a word with
Chris before we start splitting the doc. Other docs-team people had a
similar opinion as well, so I guess it's only a matter of time before we
end up having the above format.

> It could also be used as a reference thing, e.g. on a kernel bug, I'll say
> "please try this patch", user says "how?", it would be nice if i could point
> them to a specific page on the tech doc.

Very valid point. Thanks for the inputs Daniel! :)

Regards,

- --
Shyam Mani | <fox2mike@gentoo.org>
docs-team | http://gdp.gentoo.org
GPG Key | 0xFDD0E345
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFC0YGFYZNYgP3Q40URAsACAJ9q3nWpqaJlTvAXUHIQq0iuSKuqRQCeN3cn
Apy9mAtQymYDYRXGy/kkMQY=
=SBEp
-----END PGP SIGNATURE-----
--
gentoo-dev@gentoo.org mailing list

Shyam Mani wrote:
> As for the rest of the points you've brought up, did you have time to
> pen down answers as well? If so, could we have a look at them please?
> Some answers are obvious, but some others aren't and these points are
> quite valid and do need to be in the doc.

I haven't written any answers. I was planning to write this document based on
those points, but never got around to it.

I'm happy to modify the document to cover my points, but I don't know when I'd
get time to do so. So if you or anyone else want to takes the job, feel free ;)
If you'd like me to elaborate on any points, just ask.

Thanks,
Daniel
--
gentoo-dev@gentoo.org mailing list

On 15:57 Sun 10 Jul , Daniel Drake wrote:
> How to give us lots of yummy info:
> - How to apply patches
> - How to use strace
> - How to identify a configure failure
> - and how to upload config.log
> - How to use gdb, for C apps
> - Using valgrind?
> etc....

Tigger wrote a doc about writing helpful bug reports for the auditing
team which covers some of this. I can't remember the url, so someone
might like to poke him about it if he isn't paying attention to this
discussion.

Dave

--
gentoo-dev@gentoo.org mailing list

Chris White wrote:
>>never reassign a bug
>
>
> Ok, I have a section on how to re-assign the bug to the maintainer if you're the reporter, so you don't want that at all is what you're saying? Just let bug-wranglers handle it?

Yes, I'm pretty much saying that. Thinking back to the situation that prompted
me to note this down, a kernel bug came in. bug-wranglers assigned it to
kernel. The reporter then reassigned it to me(!?) without me even responding,
with a comment like, "dsd this one is for you". Since when do our users get to
choose which developer fixes their bug? I found this quite rude and replied
with a (probably too harsh) comment and reassigned it back to kernel. The user
then sent me an apologetic email, stating that he didn't know much about
Gentoo development and asked me to explain the reassignment procedures.

My response to that: Just leave reassignment to the developers (wranglers
included).

>>always try the testing package before reporting bug
>
>
> Not sure what you mean by this. I'd assume they would have already tested the package in order to have hit the bug?

If v3.2.1 is stable, and v3.2.2 is ~arch, and they found the bug on v3.2.1,
then they should also try v3.2.2 before filing the bug. Thats all I was
thinking of.

>>how to apply patches in general
>
>
> I need a clearer example of this. Do you mean applying kernel patches? Most users will just need to know how to patch ebuilds and add epatch lines to ebuilds, I'm not sure of anything else.

I mean applying patches using patch. So yes, kernel patches would be included
under that. And I imagine there are many situations (for non-kernel stuff)
where using patch is easier than epatch.

For example, to add a patch to a small ebuild package, you can either create
an overlay, copy the ebuild over, modify the ebuild to add epatch (this
involves being able to find the right function in the ebuild, possibly even
_creating_ a src_unpack function, requiring a lot of knowledge from the user),
make a filesdir, put patch in filesdir, emerge.

Or:

cd /usr/portage/blah/blah
ebuild blah.ebuild unpack
pushd /var/tmp/portage/blah/work/blah
patch -p1 /path/to/patch
popd
ebuild blah.ebuild merge

I think the latter version is easier since it doesn't require as much
background knowledge. And the patch technique is useful to know for if you
need to patch a kernel or something like that.

Daniel
--
gentoo-dev@gentoo.org mailing list

Daniel Drake posted <42D649CE.3070101@gentoo.org>, excerpted below, on
Thu, 14 Jul 2005 12:17:34 +0100:

> Chris White wrote:
>>>never reassign a bug
>>
>>
>> Ok, I have a section on how to re-assign the bug to the maintainer if
>> you're the reporter, so you don't want that at all is what you're
>> saying? Just let bug-wranglers handle it?
>
> Yes, I'm pretty much saying that. Thinking back to the situation that
> prompted me to note this down, a kernel bug came in. bug-wranglers
> assigned it to kernel. The reporter then reassigned it to me(!?) without
> me even responding, with a comment like, "dsd this one is for you". Since
> when do our users get to choose which developer fixes their bug? I found
> this quite rude and replied with a (probably too harsh) comment and
> reassigned it back to kernel. The user then sent me an apologetic email,
> stating that he didn't know much about Gentoo development and asked me to
> explain the reassignment procedures.
>
> My response to that: Just leave reassignment to the developers (wranglers
> included).

Counter-example. The amd64 team specifically mentions in their
documentation on keywording that keyword bugs can be specifically assigned
to amd64. Likewise with the multilib-strict bugs, they were to be
assigned to amd64. Of course, that's an arch team, not an individual
developer, but the point stands, if these bugs are being filed on specific
request of some team or individual developer (as with testing of some
package or another), there's no reason to bother bug-wranglers with it,
when all they are going to do is assign it to the same folks that
requested it, that got the user testing and filing the bug in the first
place!

So... something like the following (first draft off the top of my head,
can probably be rewritten rather better than this):

"Leave the bug assignment alone, unless you are sure you know who to
assign it to. For most bugs and reporters, that means let the
bug-wranglers handle it, unless the bug has been filed in response to a
specific request by the package maintainer/herd or your arch team. If you
are reading this, it probably means leave it alone."

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman in
http://www.linuxdevcenter.com/pub/a/linux/2004/12/22/rms_interview.html


--
gentoo-dev@gentoo.org mailing list