Bugzilla/Bug report guide

Other languages:

Best practices

Reread the text before submission, the text cannot be edited afterwards. Also any text entered into a bug report will be usually e-mailed immediately to many people. Write in precise and clean language and avoid colloquial speech. Hint: Imagine you have only one chance in your life to write this very important bug report. You know that the recipient can read English, but it is not his native language.

Search for duplicates, before creating a new bug.

Stay on topic - A bug ticket is used for technical reports and chitchat should be avoided. Keep them in the support channels (forums, IRC or mailing lists).
Confirm the existence of a problem only once. - It does not help solving the problem, if you and another person report it twice. But if your and the confirmer's systems differ in an obvious way and that would be helpful to know, add this information.
Open one bug ticket per topic - Usually this means not more than one package and one bug per ticket. If your problem is not discussed on a bug, search for one related to your issue or create a new report. Do not hijack bugs.
No talk on TRACKER bugs. - Those bugs are meta bugs. If you want to add useful information, add them to a related sub bug or create a new bug.
Optional: Gentoo consultants provide also commercial support for bugs and ebuilds.
Attach the logs to the bug ticket if the ticket is about problems during runtime or installation.

Packages/ebuild

You should always add information about your system configuration to the bug. To do so, create a new attachment and paste the contents of:

user $emerge --info > /tmp/emerge--info.txt

Report a build-time bug (emerge failed)

Error creating thumbnail: File missing

Use the Add an attachment button below the description text box in order to attach files in bugzilla.

First write the exact version of the package in the title of the bug report e.g. sys-apps/package-2.3-r4
Add a short description to the title.
Attach the logs to the bug ticket

Report a run-time bug

Files and information of interest ordered by priority:

The exact version of the package in the title of the bug report e.g. sys-apps/package-2.3-r4 crashes with error: Cannot proceed...
Description of the problem, so that other can reproduce it:
- How is the program run (on the console, in a terminal, as a daemon, in what runlevel etc.)
- Any error output
- What makes the program crash, behave wrong, not start
- Is there a workaround?
- What was the last working version of the package, if any?
- What changed to make it not work?
Attach the logs to the bug ticket

Report a version bump; a newer upstream release is available since a while

Search Bugzilla before posting a bump request - is there already a bug open? Has the local Portage tree been synced lately; is it already in Portage?
Avoid zero-day bump requests (wait at least 48 hours after the release announcement)
Has it actually been released by upstream sources, or is it just marked in the source tree? Some projects mark a release in the tree long time before it is officially released.
Be sure to mention if it compiles and runs well on your arch. Any other helpful information you provide is most welcome.
Add a link to the upstream website
Give a link or list of fixed bugs or new features (sometimes called changelog)
Write a summary in the form app-editors/vim-12.3.5 version bump

Optional

Does a simple copy work, or does the ebuild need changes? (changed dependencies, obsolete patch files)
Test the ebuild in a local overlay before submitting attachments
Provide patches for proposed ebuild edits, with optional explanation of changes (file name should match the new version number, not old)
Provide additional files (initd, unit files) as separate attachments (as needed)
Do not paste files directly into comments; use attachments.

Request for a new package; ebuild request

If you request a new ebuild for a software to be added to portage, you must find or become a maintainer for the package:

Link to the upstream website in the bug report
Give a link or list of features
Suggest a preliminary category and package name for the ebuild in the subject line for example media-gfx/inkscape ebuild request
Provide an ebuild and patches that were tested in your local overlay (you can get help in IRC or in the forums with that)

Package XY should be marked stable

If a package is building and working without problems on the system for more than 30 days and it isn't yet marked as stable you can create a stable request.

Kernel

Files and information of interest for kernel bug reports ordered by priority:

Which kernel and version is used, on what architecture e.g. gentoo-sources-3.4.2-r2 on x86_64
The kernel configuration file should be attached to the bug report (/usr/src/linux/.config)
A list of all devices in the system can be acquired with lspci -k
Log files during kernel initialization should be attached (/var/log/dmesg or /var/log/messages)

Note
On request a kernel git-bisect could be done to identify bad patches.