Page MenuHomeFreeBSD
Files F136571027

D53778.id.diff
No OneTemporary
Actions

D53778.id.diff
View Options

diff --git a/documentation/content/en/articles/problem-reports/_index.adoc b/documentation/content/en/articles/problem-reports/_index.adoc
--- a/documentation/content/en/articles/problem-reports/_index.adoc
+++ b/documentation/content/en/articles/problem-reports/_index.adoc
@@ -77,7 +77,7 @@
So how does one determine what is a bug and what is not? As a simple rule of thumb, the problem is _not_ a bug if it can be expressed as a question (usually of the form "How do I do X?" or "Where can I find Y?").
It is not always quite so black and white, but the question rule covers a large majority of cases.
-When looking for an answer, consider posing the question to the {freebsd-questions}.
+When looking for an answer, consider first consulting the https://forums.freebsd.org[FreeBSD Forums], IRC, or the {freebsd-questions}.
Consider these factors when submitting reports about ports or other software that is not part of FreeBSD itself:
@@ -99,9 +99,9 @@
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.
-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.
+If the problem is in the base system, first read the extref:{handbook}/cutting-edge/[Handbook section on Versions], 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.
-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/#sup[list of supported versions].
If the problem is in a port, consider filing a bug with the upstream.
The FreeBSD Project can not fix all bugs in all software.
@@ -114,8 +114,10 @@
You should therefore check all the obvious places before submitting your problem report.
For FreeBSD, this means:
-* 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].
+* First, always check to see if the problem is covered in extref:{handbook}current-stable/[Handbook].
+* The FreeBSD extref:{faq}[Frequently Asked Questions] (FAQ) list. The FAQ attempts to provide answers for several questions, such as those concerning extref:{faq}[hardware compatibility, hardware].
* The extref:{handbook}eresources/[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.
+* As noted above, the FreeBSD Forums and IRC.
* 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 Bugzilla database]. 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.
@@ -139,8 +141,10 @@
* _Avoid using a weak "Summary" line._ You should not assume that anyone reading your PR has any context for your submission, so the more you provide, the better. For instance, what part of the system does the problem apply to? Do you only see the problem while installing, or while running? To illustrate, instead of `Summary: portupgrade is broken`, see how much more informative this seems: `Summary: port ports-mgmt/portupgrade coredumps on -current`. (In the case of ports, it is especially helpful to have both the category and portname in the "Summary" line.)
* _If you have a patch, say so._
The presence of a patch makes it much easier to progress a report.
-** Do not use the `patch` or `patch-ready` keywords – they are deprecated.
-* _If you are a maintainer, say so._ If you are maintaining a part of the source code (for instance, an existing port), you definitely should set the "Class" of your PR to `maintainer-update`. This way any committer that handles your PR will not have to check.
+** Do not use the `patch` or `patch-ready` keywords – they are deprecated. Instead, include your patch as an Attachment, and click the '[patch]' checkbox. (If you do not see the checkbox, click `Show Advanced Fields` in the upper left corner.)
+** Patches with MIME type 'text/plain' are preferred.
+** Patches compatible with `git` are preferred.
+* _If you are a ports maintainer, say so._ If you are maintaining a part of the source code (for instance, an existing port), you definitely should set the `maintainer-feedback?` of your PR to `+`. This way any committer that handles your PR will not have to check.
* _Be specific._ The more information you supply about what problem you are having, the better your chance of getting a response.
** Include the version of FreeBSD you are running (there is a place to put that, see below) and on which architecture. You should include whether you are running from a release (e.g., from a CD-ROM or download), or from a system maintained by Git (and, if so, what hash and branch you are at). If you are tracking the FreeBSD-CURRENT branch, that is the very first thing someone will ask, because fixes (especially for high-profile problems) tend to get committed very quickly, and FreeBSD-CURRENT users are expected to keep up.
@@ -162,7 +166,7 @@
*** the fact that you have read [.filename]#ports/UPDATING# and that your problem is not listed there (someone is guaranteed to ask)
* _Avoid vague requests for features._ Problem Reports of the form "someone should really implement something that does so-and-so" are less likely to get results than very specific requests. Remember, the source is available to everyone, so if you want a feature, the best way to ensure it being included is to get to work! Also consider the fact that many things like this would make a better topic for discussion on `freebsd-questions` than an entry in the PR database, as discussed above.
-* _Make sure no one else has already submitted a similar PR._ Although this has already been mentioned above, it bears repeating here. It only take a minute or two to use the web-based search engine at https://bugs.freebsd.org/bugzilla/query.cgi[https://bugs.freebsd.org/bugzilla/query.cgi]. (Of course, everyone is guilty of forgetting to do this now and then.)
+* _Make sure no one else has already submitted a similar PR._ Although this has already been mentioned above, it bears repeating here. It only take a minute or two to use the Bugzilla web-based search engine at https://bugs.freebsd.org/bugzilla/query.cgi[https://bugs.freebsd.org/bugzilla/query.cgi]. (Of course, everyone is guilty of forgetting to do this now and then.)
* _Report only one issue per Problem Report._ Avoid including two or more problems within the same report unless they are related. When submitting patches, avoid adding multiple features or fixing multiple bugs in the same PR unless they are closely related-such PRs often take longer to resolve.
* _Avoid controversial requests._ If your PR addresses an area that has been controversial in the past, you should probably be prepared to not only offer patches, but also justification for why the patches are "The Right Thing To Do". As noted above, a careful search of the mailing lists using the archives at https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] is always good preparation.
* _Be polite._ Almost anyone who would potentially work on your PR is a volunteer. No one likes to be told that they have to do something when they are already doing it for some motivation other than monetary gain. This is a good thing to keep in mind at all times on Open Source projects.
@@ -178,24 +182,27 @@
[[pr-writing-attaching-patches]]
== Attaching Patches or Files
-The following instructions apply not only to submissions via Bugzilla, but also via Phabricator or the FreeBSD Github instance.
+The following instructions apply not only to Problem Report submissions via Bugzilla, but also via Phabricator or the FreeBSD Github instance
+(as Pull Requests).
-In general, we recommend using `git format-patch` to generate one or a series of unified diff against the base
+In general, we strongly prefer using `git format-patch` to generate one or a series of unified diffs against the base
branch (e.g. `origin/main`).
Patches generated this way would include the Git hashes and will include your name and email address, making it
easier for committers to apply your patch and properly credit you as the author (using `git am`).
For minor changes where you prefer not to use git, please be sure to use man:diff[1] with the `-u` option to
create a unified diff, as this would give developers more context and are more readable than other diff formats.
+Please base your patch(es) at the base of the appropriate tree.
For problems with the kernel or the base utilities, a patch against FreeBSD-CURRENT (the main Git branch) is preferred since all new code should be applied and tested there first.
After appropriate or substantial testing has been done, the code will be merged/migrated to the FreeBSD-STABLE branch.
-If you attach a patch inline, instead of as an attachment, note that the most common problem by far is the tendency of some email programs to render tabs as spaces, which will completely ruin anything intended to be part of a Makefile.
+We prefer patches as attachments. However, if you attach a patch inline, note that the most common problem by far is the tendency of some email programs to render tabs as spaces, which will completely ruin anything intended to be part of a Makefile.
Do not send patches as attachments using `Content-Transfer-Encoding: quoted-printable`.
These will perform character escaping and the entire patch will be useless.
+Please simply use MIME type `text/plain'.
-Also note that while including small patches in a Pull Request is generally all right—particularly when they fix the problem described in the Pull Request-large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the Pull Request instead of the patch.
+Also note that while including small patches in a Github Pull Request is generally all right—particularly when they fix the problem described in the Pull Request-large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the Pull Request instead of the patch.
Patches in email tend to get mangled, and the larger the patch, the harder it will be for interested parties to unmangle it.
Also, posting a patch on the web allows you to modify it without having to resubmit the entire patch in a followup.
Finally, large patches simply increase the size of the database, since closed reports are not actually deleted but instead kept and simply marked as complete.
@@ -205,6 +212,8 @@
[[pr-writing-filling-template]]
== Filling out the Bugzilla Form
+The following instructions apply only to submissions via Bugzilla.
+
[NOTE]
====
The email address you use will become public information and may become available to spammers.
@@ -240,7 +249,7 @@
** If the problem would otherwise be filed in `kern` but has to do with the USB subsystem, the correct choice is `usb`.
** If the problem would otherwise be filed in `kern` but has to do with the threading libraries, the correct choice is `threads`.
** If the problem would otherwise be in the base system, but has to do with our adherence to standards such as POSIX(R), the correct choice is `standards`.
-** If you are convinced that the problem will only occur under the processor architecture you are using, select one of the architecture-specific categories: commonly `i386` for Intel-compatible machines in 32-bit mode; `amd64` for AMD machines running in 64-bit mode (this also includes Intel-compatible machines running in EMT64 mode); and less commonly `arm` or `powerpc`.
+** If you are convinced that the problem will only occur under the processor architecture you are using, select one of the architecture-specific categories: commonly `i386` for Intel-compatible machines in 32-bit mode; `amd64` for AMD machines running in 64-bit mode (this also includes Intel-compatible machines running in EMT64 mode); and less commonly `arm`, `powerpc`, or `riscv64`.
+
[NOTE]
====
@@ -258,7 +267,7 @@
====
You are having a problem with an add-in peripheral card on a commonly seen bus, or a problem with a particular type of hard disk drive: in this case, it probably applies to more than one architecture, and `kern` is the right category.
====
-** If you really do not know where the problem lies (or the explanation does not seem to fit into the ones above), use the `misc` category. Before you do so, you may wish to ask for help on the {freebsd-questions} first. You may be advised that one of the existing categories really is a better choice.
+** If you really do not know where the problem lies (or the explanation does not seem to fit into the ones above), use the `misc` category. Before you do so, you may wish to ask for help first. You may be advised that one of the existing categories really is a better choice.
* _Environment:_ This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other installed software that influences the problem, etc.—quite simply everything a developer needs to know to reconstruct the environment in which the problem occurs.
* _Description:_ A complete and accurate description of the problem you are experiencing. Try to avoid speculating about the causes of the problem unless you are certain that you are on the right track, as it may mislead a developer into making incorrect assumptions about the problem. It should include the actions you need to take to reproduce the problem. If you know any workaround, include it. It not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem.

File Metadata

Mime Type
text/plain
Expires
Wed, Nov 19, 9:51 AM (7 h, 31 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
25402248
Default Alt Text
D53778.id.diff (14 KB)

Event Timeline