Differential D31926 Diff 97856 documentation/content/en/articles/problem-reports/_index.adoc

Changeset View

Standalone View

documentation/content/en/articles/problem-reports/_index.adoc

Context not available.
	:sectnumlevels: 6	:sectnumlevels: 6
	:source-highlighter: rouge	:source-highlighter: rouge
	:experimental:	:experimental:
		:images-path: articles/problem-reports/
	ifeval::["{backend}" == "html5"]
	include::shared/en/mailing-lists.adoc[]	ifdef::env-beastie[]
	include::shared/en/urls.adoc[]	ifdef::backend-html5[]
		include::shared/authors.adoc[]
		include::shared/mirrors.adoc[]
		include::shared/releases.adoc[]
		include::shared/attributes/attributes-{{% lang %}}.adoc[]
		include::shared/{{% lang %}}/teams.adoc[]
		include::shared/{{% lang %}}/mailing-lists.adoc[]
		include::shared/{{% lang %}}/urls.adoc[]
		:imagesdir: ../../../images/{images-path}
		endif::[]
		ifdef::backend-pdf,backend-epub3[]
		include::../../../../shared/asciidoctor.adoc[]
	endif::[]	endif::[]

	ifeval::["{backend}" == "pdf"]
	include::../../../../shared/en/mailing-lists.adoc[]
	include::../../../../shared/en/urls.adoc[]
	endif::[]	endif::[]

	ifeval::["{backend}" == "epub3"]	ifndef::env-beastie[]
	include::../../../../shared/en/mailing-lists.adoc[]	include::../../../../../shared/asciidoctor.adoc[]
	include::../../../../shared/en/urls.adoc[]
	endif::[]	endif::[]

	[.abstract-title]	[.abstract-title]
Context not available.

	* Please do not submit problem reports that simply state that a newer version of an application is available. Ports maintainers are automatically notified by portscout when a new version of an application becomes available. Actual patches to update a port to the latest version are welcome.	* Please do not submit problem reports that simply state that a newer version of an application is available. Ports maintainers are automatically notified by portscout when a new version of an application becomes available. Actual patches to update a port to the latest version are welcome.
	* For unmaintained ports (`MAINTAINER` is `ports@FreeBSD.org`), a PR without an included patch is unlikely to get picked up by a committer. To become the maintainer of an unmaintained port, submit a PR with the request (patch preferred but not required).	* For unmaintained ports (`MAINTAINER` is `ports@FreeBSD.org`), a PR without an included patch is unlikely to get picked up by a committer. To become the maintainer of an unmaintained port, submit a PR with the request (patch preferred but not required).
	* In either case, following the process described in link:{porters-handbook}#port-upgrading[Porter's Handbook] will yield the best results. (You might also wish to read link:{contributing}#ports-contributing[Contributing to the FreeBSD Ports Collection].)	* In either case, following the process described in extref:{porters-handbook}[Porter's Handbook, port-upgrading] will yield the best results. (You might also wish to read extref:{contributing}[Contributing to the FreeBSD Ports Collection, ports-contributing].)

	A bug that cannot be reproduced can rarely be fixed.	A bug that cannot be reproduced can rarely be fixed.
	If the bug only occurred once and you cannot reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong.	If the bug only occurred once and you cannot reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong.
Context not available.
	Then, ascertain whether the problem is timely.	Then, ascertain whether the problem is timely.
	There are few things that will annoy a developer more than receiving a problem report about a bug she has already fixed.	There are few things that will annoy a developer more than receiving a problem report about a bug she has already fixed.

	If the problem is in the base system, first read the FAQ section on link:{faq}#LATEST-VERSION[FreeBSD versions], if you are not already familiar with the topic.	If the problem is in the base system, first read the FAQ section on extref:{faq}[FreeBSD versions, LATEST-VERSION], if you are not already familiar with the topic.
	It is not possible for FreeBSD to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs.	It is not possible for FreeBSD to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs.
	The Security Officer team maintains the link:https://www.FreeBSD.org/security/[list of supported versions].	The Security Officer team maintains the link:https://www.FreeBSD.org/security/[list of supported versions].

Context not available.
	You should therefore check all the obvious places before submitting your problem report.	You should therefore check all the obvious places before submitting your problem report.
	For FreeBSD, this means:	For FreeBSD, this means:

	* The FreeBSD link:{faq}[Frequently Asked Questions] (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning link:{faq}#hardware[hardware compatibility], link:{faq}#applications[user applications], and link:{faq}#kernelconfig[kernel configuration].	* The FreeBSD extref:{faq}[Frequently Asked Questions] (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning extref:{faq}[hardware compatibility, hardware], extref:{faq}[user applications, applications], and extref:{faq}[kernel configuration, kernelconfig].
	* The link:{handbook}#eresources-mail[mailing lists]-if you are not subscribed, use https://www.FreeBSD.org/search/#mailinglists[the searchable archives] on the FreeBSD web site. If the problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something that has been overlooked.	* The extref:{handbook}[mailing lists, eresources-mail]-if you are not subscribed, use https://www.FreeBSD.org/search/#mailinglists[the searchable archives] on the FreeBSD web site. If the problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something that has been overlooked.
	* Optionally, the entire web-use your favorite search engine to locate any references to the problem. You may even get hits from archived mailing lists or newsgroups you did not know of or had not thought to search through.	* Optionally, the entire web-use your favorite search engine to locate any references to the problem. You may even get hits from archived mailing lists or newsgroups you did not know of or had not thought to search through.
	* Next, the searchable https://bugs.freebsd.org/bugzilla/query.cgi[FreeBSD PR database] (Bugzilla). Unless the problem is recent or obscure, there is a fair chance it has already been reported.	* Next, the searchable https://bugs.freebsd.org/bugzilla/query.cgi[FreeBSD PR database] (Bugzilla). Unless the problem is recent or obscure, there is a fair chance it has already been reported.
	* Most importantly, attempt to see if existing documentation in the source base addresses your problem.	* Most importantly, attempt to see if existing documentation in the source base addresses your problem.
Context not available.

	There are a few ways to do so, ideally in the following order, with a few days between attempting each communication channel:	There are a few ways to do so, ideally in the following order, with a few days between attempting each communication channel:

	* Find the relevant FreeBSD mailing list for the problem report from the link:{handbook}#eresources-mail[list in the Handbook] and send a message to that list asking about assistance or comments on the problem report.	* Find the relevant FreeBSD mailing list for the problem report from the extref:{handbook}[list in the Handbook, eresources-mail] and send a message to that list asking about assistance or comments on the problem report.
	* Join the relevant IRC channels. A partial listing is here: https://wiki.freebsd.org/IrcChannels[]. Inform the people in that channel about the problem report and ask for assistance. Be patient and stay in the channel after posting, so that the people from different time zones around the world have a chance to catch up.	* Join the relevant IRC channels. A partial listing is here: https://wiki.freebsd.org/IrcChannels[]. Inform the people in that channel about the problem report and ask for assistance. Be patient and stay in the channel after posting, so that the people from different time zones around the world have a chance to catch up.
	* Find committers interested in the problem that was reported. If the problem was in a particular tool, binary, port, document, or source file, check the https://cgit.FreeBSD.org[Git Repository]. Locate the last few committers who made substantive changes to the file, and try to reach them via IRC or email. A list of committers and their emails can be found in the link:{contributors}[Contributors to FreeBSD] article.	* Find committers interested in the problem that was reported. If the problem was in a particular tool, binary, port, document, or source file, check the https://cgit.FreeBSD.org[Git Repository]. Locate the last few committers who made substantive changes to the file, and try to reach them via IRC or email. A list of committers and their emails can be found in the extref:{contributors}[Contributors to FreeBSD] article.

	Remember that these people are volunteers, just like maintainers and users, so they might not be immediately available to assist with the problem report.	Remember that these people are volunteers, just like maintainers and users, so they might not be immediately available to assist with the problem report.
	Patience and consistency in the follow-ups is highly advised and appreciated.	Patience and consistency in the follow-ups is highly advised and appreciated.
Context not available.
	It is by no means complete.	It is by no means complete.

	* https://github.com/smileytechguy/reporting-bugs-effectively/blob/master/ENGLISH.md[How to Report Bugs Effectively]-an excellent essay by Simon G. Tatham on composing useful (non-FreeBSD-specific) problem reports.	* https://github.com/smileytechguy/reporting-bugs-effectively/blob/master/ENGLISH.md[How to Report Bugs Effectively]-an excellent essay by Simon G. Tatham on composing useful (non-FreeBSD-specific) problem reports.
	* link:{pr-guidelines}[Problem Report Handling Guidelines]-valuable insight into how problem reports are handled by the FreeBSD developers.	* extref:{pr-guidelines}[Problem Report Handling Guidelines]-valuable insight into how problem reports are handled by the FreeBSD developers.
Context not available.