From c9a087a388cc7c4368cceed218815ed4022377fe Mon Sep 17 00:00:00 2001 From: Mark Linimon Date: Sat, 22 Oct 2005 07:03:20 +0000 Subject: [PATCH] Major additions of text to this article: - continue to add more information that is specific to the web-based form as opposed to send-pr(1). In particular, mention problems that are particular to that method. - greatly expand the text sections about various fields such as 'categories' to try to adddress continuing misunderstanding on the part of our users. - discuss the fact that spammers will most likely find your email address from a GNATS submission. - demote kernel panics to 'serious' to represent commonly accepted usage. Reserve 'critical' for data corruption issues or things that would be considered 'showstoppers' for an upcoming release. (I am using my bugmeister hat for this change.) - reiterate that serious security problems should go to secteam, not into GNATS. - document the common problems seen when submitting PRs, including our anti-spam measures and the 'lost PR' index problem. - deprecate the use of HTML-only messages. Regression testing using the spam filters shows that close to 100% of such messages are spam. (The filters have been tuned to correctly pass HTML that is included in patches but reject HTML that conforms to all the common abuse patterns. I am using my bugmeister hat for this change). --- .../articles/problem-reports/article.sgml | 175 ++++++++++++++++-- 1 file changed, 157 insertions(+), 18 deletions(-) diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml index 09163484f6..cc329d65fb 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ b/en_US.ISO8859-1/articles/problem-reports/article.sgml @@ -527,6 +527,8 @@
Attaching patches or files + The following applies to submitting PRs via email: + The &man.send-pr.1; program has provisions for attaching files to a problem report. You can attach as many files as you want provided that each has a unique base name (i.e. the @@ -586,6 +588,8 @@
Filling out the template + The next section applies to the email method only: + When you run &man.send-pr.1;, you are presented with a template. The template consists of a list of fields, some of which are pre-filled, and some of which have comments explaining @@ -604,7 +608,8 @@ adding one or more email addresses to the Cc: header. - Next comes a series of single-line fields: + In the email template you will find the following two + single-line fields: @@ -621,12 +626,31 @@ CVSup. + + + The next section describes fields that are common to both + the email interface and the web interface: + + + - Originator: This is normally + Originator: + Please specify your real name, optionally followed + by your email address in angle brackets. + In the email interface, this is normally prefilled with the gecos field of the currently logged-in - user. Please specify your real name, optionally followed - by your email address in angle brackets. + user. + + + The email address you use will become public information + and may become available to spammers. You should either + have spam handling procedures in place, or use a temporary + email account. However, please note that if you do not + use a valid email account at all, we will not be able to + ask you questions about your PR. + + @@ -645,7 +669,8 @@ As noted above, if your problem report includes a patch, please have the synopsis start with [patch]; - if you are a maintainer, you may consider adding + if this is a ports PR and you are the + maintainer, you may consider adding [maintainer update] and set the Class of your PR to maintainer-update. @@ -657,15 +682,24 @@ serious or critical. Do not overreact; refrain from labeling your problem critical - unless it really is (e.g. root exploit, easily - reproducible panic) or serious unless - it is something that will affect many users (problems with + unless it really is (e.g. data corruption issues, serious + regression from previous functionality in -CURRENT) + or serious unless + it is something that will affect many users (kernel + panics or freezes; problems with particular device drivers or system utilities). &os; developers will not neccesarily work on your problem faster if you inflate its importance since there are so many other people who have done exactly that — in fact, some - developers pay little attention to this field, and the next, + developers pay little attention to this field because of this. + + + Major security problems should not + be filed in GNATS, because all GNATS information is public + knowledge. Please send such problems in private email to + &a.security-officer;. + @@ -675,12 +709,40 @@ be reserved for problems that will affect practically every user of &os; and medium for something that will affect many users. + + + This field has become so widely abused that it is + almost completely meaningless. + - Category: Choose one of the - following (taken from + Category: Choose an appropriate + category. + + + There are a number of "platform" categories into which + bugs in the base system that are specific to one particular + hardware architecture should be filed. Problems that are + generic all across versions of &os; should probably be + filed as kern or bin; + see discussion of those categories below. + + Example: you have a common PC-based machine, and think + you have encountered a problem specific to a particular + chipset or a particular motherboard: i386 + is the right category. + + Example: 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. + + + Here is the current list of categories (taken from ): + advocacy: problems relating to @@ -699,12 +761,18 @@ bin: problems with userland - programs in the base system. + programs in the base system. If running &man.whereis.1; + shows /bin, /usr/sbin, + or something similar, then this is probably the right + category. (A few contributed programs might instead + need to be in gnu; see below.) conf: problems with - configuration files, default values etc. + configuration files, default values, and so forth. + Things that affect /usr/share + or /etc/rc* belong here. @@ -713,7 +781,7 @@ - gnu: problems with GNU software + gnu: problems with imported GNU software such as &man.gcc.1; or &man.grep.1;. @@ -736,12 +804,18 @@ kern: problems with - the kernel or (non-platform-specific) device drivers. + the kernel, (non-platform-specific) device drivers, + or the base libraries. misc: anything that does not fit - in any of the other categories. (Note that it is + in any of the other categories. (Note that there is + almost nothing that truly belongs in this category, + except for problems with the release and build + infrastructure. Temporary build failures on + HEAD do not belong here. Also note + that it is easy for things to get lost in this category). @@ -777,7 +851,10 @@ www: Changes or enhancements to - the &os; website. + the &os; website. + Problems with code found in /usr/ports/www + do not belong here, they belong in + ports instead. @@ -816,7 +893,8 @@ Release: The version of &os; - that you are running. This is filled out automatically by + that you are running. This is filled out automatically if + you are using &man.send-pr.1; and need only be changed if you are sending a problem report from a different system than the one that exhibits the problem. @@ -867,6 +945,8 @@
Sending off the problem report + If you are using &man.send-pr.1;: + Once you are done filling out the template, have saved it, and exit your editor, &man.send-pr.1; will prompt you with s)end, e)dit or a)bort?. You can then hit @@ -884,6 +964,26 @@ This will read the specified file, validate the contents, strip comments and send it off. + + If you are using the web form: + + Before you hit submit, you will need to + fill in a field containing text that is represented in image + form on the page. This unfortunate measure has had to be + adopted due to misuse by automated systems and a few misguided + individuals. It is a necessary evil that no one likes; please + do not ask us to remove it. + + Note that you are strongly advised to + save your work somewhere before hitting submit. + A common problem for users is to have their web browser displaying + a stale image from its cache. If this happens to you, your + submission will be rejected and you may lose your work. + + If you are unable to view images for any reason, and are also + unable to use &man.send-pr.1;, please accept our apologies for + the inconvenience and email your problem report to the bugbuster + team at freebsd-bugbusters@FreeBSD.org.
@@ -943,6 +1043,45 @@ possible, explaining how or when the problem was fixed.
+
+ If you are having problems + + Most PRs go through the system and are accepted quickly; + however, at times GNATS runs behind and you may not get your + email confirmation for 10 minutes or even longer. Please try to + be patient. + + In addition, because GNATS receives all its input via email, + it is absolutely vital that &os; runs all its submissions through + spam filters. If you do not get a response within an hour or + two, you may have fallen afoul of them; if so, please contact + the GNATS administrators at bugmeister@FreeBSD.org + and ask for help. + + + Among the anti-spam measures is one that weighs against + many common abuses seen HTML-based email (although not necessarily + the mere inclusion of HTML in a PR). We strongly recommend + against the use of HTML-based email when sending PRs: not + only is it more likely to fall afoul of the filters, it also + tends to merely clutter up the database. Plain old email is + strongly preferred. + + + On rare occasions you will encounter a GNATS bug where a + PR is accepted and assigned a tracking number but it does not + show up on the list of PRs on any of the web query pages. What + may have happened is that the database index has gotten out of + synchronization with the database itself. The way that you + can test whether this has happened is to pull up the + + view a single PR page and see whether the PR shows up. + If it does, please notify the GNATS administrators at + bugmeister@FreeBSD.org. Note that there is a + cron job that periodically rebuilds the database, + so unless you are in a hurry, no action needs to be taken. +
+
Further Reading