Bugzilla/漏洞报告指南

This article explains how to report bugs on the Gentoo Bugzilla.

See Bugzilla/Guide for the recommended method of reporting bugs for Gentoo.

最佳实践

• 提交前请重新阅读文本，之后文本无法编辑。此外，任何输入到漏洞报告中的文本通常都会立即通过电子邮件发送给许多人。用准确和干净的语言写作并且避免口语化。 提示： 想象一下，你一生中只有一次机会来撰写这份非常重要的漏洞报告。你知道收件人可以阅读英语，但这不是他的母语。

• 在创建新的漏洞报告之前搜索重复项。

• Stay on topic - A bug ticket is used for technical reports and chitchat should be avoided. Keep discussions 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.

包/ebuild

你应该始终将有关系统配置的信息添加到漏洞报告中。为此，请创建一个新附件并粘贴以下内容：

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

报告构建时漏洞（emerge 失败）

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

报告运行时漏洞

按优先级排序的感兴趣的文件和信息：

• 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

选项

• 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.

请求一个新的包；ebuild 请求

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

If a bug report already exists for the package, you can help the effort by keeping information about the package up to date. If you add a -VERSION component to the package atom, then this can be updated with new releases over time while the bug report remains unmaintained to show there is a continuing interest in seeing it integrated into the portage tree.

If no bug report exists for the package, you can file a bug report under the Gentoo Linux project and the component New package.

The Summary of your bug report should list a (preliminary) package atom category/package, perhaps with a -VERSION suffix, followed by a canonical short description of the package (the DESCRIPTION variable in an ebuild). It is important to disambiguate the name of the new package: if upstream uses different names for the same software, perhaps an abbreviation as well as the full name, you should mention both (all) of these in the Summary so that other people can find bug reports about the same software. If several (groups of) people track different bug reports about virtually the same ebuild request, this will duplicate the effort of ebuild research and development, and will divide people who have a common interest.

You should link to the upstream website (the HOMEPAGE variable in an ebuild) using the URL field. You should provide a list of features in the Description of the bug report. This may well be taken directly from the upstream website or from a manual or other documentation, and could be used later for the longdescription tag in metadata.xml.

You can attach an ebuild and related files that should go into the portage tree directly to the bug report, or you can use the See also field to refer to a git pull request.

You can help develop the package by setting up a local overlay with your ebuilds, metadata, patches and other auxiliary files. If you need technical support with your ebuild development, many people would be glad to help.

Request stabilization

提示
For developers, the devmanual has more extensive information on stable requests.

A bug ticket can be used for a stable request.

Everybody can request a stabilization. Users do not need to worry about filling all fields or details in the bug. The maintainer (or Proxied Maintainer) will CC the arches.

To request stabilization of a package, file a new bug under the Stabilization component taking care to complete two special bug fields:

• Package list - a fully qualified package per line, optionally followed by a space-delimited list of architectures to target. If no architecture list is provided, all architectures in CC are assumed. Formerly, this field was called Atoms to stabilize and contained fully qualified atoms, which is also still supported.
• Runtime testing required - indicates if additional runtime testing should be performed beyond build and tests passing. If undefined the arch tester should use their best judgement

Examples:

Summary	foo-libs/libbar-1.2.3 stabilization request
CC	amd64 x86
Runtime testing required	No
Package list	foo-libs/libbar-1.2.3 (old syntax, still supported: =foo-libs/libbar-1.2.3)
Explanation	foo-libs/libbar-1.2.3 will be stabilized for amd64 and x86 Build and tests passing is sufficient to stabilize

Summary	app-foo/bar-1.2.3 and app-foo/baz-4.5.6 stabilization request
CC	amd64 arm x86
Runtime testing required	Yes
Package list	app-foo/bar-1.2.3
	app-foo/baz-4.5.6 amd64 x86
Explanation	app-foo/bar-1.2.3 will be stabilized for amd64, arm, and x86 app-foo/baz-4.5.6 will be stabilized for amd64, and x86 It is requested additional runtime testing of the package is performed after it is merged

内核

按优先级排序的内核漏洞报告的相关文件和信息：

• 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)

附注
根据要求，可以使用 kernel git-bisect 来识别坏补丁。

Supplemental information for bug reports

Information	when needed	How to collect
SRC_URI reachable?	download failed	GENTOO_MIRRORS="" ebuild foo-1.2.ebuild fetch
OpenGL version	Games with OpenGL	glxinfo -B
linked libraries	Dependency is missing	Add missing dependency, compile, check with lddtree

Trackers

Tracker-Bugs are virtual bugs to cluster bugs with the same topic.

• Active Tracker-Bugs

另请参阅

• Attach the logs to the bug ticket — explains how to attach log files to a bug ticket
• Bugzilla/Guide — covers the recommended method of reporting bugs for Gentoo.
• Contributing to Gentoo — explains how users can contribute to the development of Gentoo
• Support — provide support for technical issues encountered when installing or using Gentoo Linux
• Troubleshooting — provide users with a set of techniques and tools to troubleshoot and fix problems with their Gentoo setups.

External references

• Gentoo's Bugzilla site