Date: Sun, 12 Aug 2018 08:46:43 +0000 (UTC) From: Eitan Adler <eadler@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r52112 - head/en_US.ISO8859-1/articles/problem-reports Message-ID: <201808120846.w7C8kh1i027841@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: eadler Date: Sun Aug 12 08:46:43 2018 New Revision: 52112 URL: https://svnweb.freebsd.org/changeset/doc/52112 Log: problem-reports: bugzilla modernization This is a simple pass over the problem-reports article to make it better describe Bugzilla. It isn't perfect, still needing content, but baby-steps. Modified: head/en_US.ISO8859-1/articles/problem-reports/article.xml Modified: head/en_US.ISO8859-1/articles/problem-reports/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/problem-reports/article.xml Sun Aug 12 08:39:16 2018 (r52111) +++ head/en_US.ISO8859-1/articles/problem-reports/article.xml Sun Aug 12 08:46:43 2018 (r52112) @@ -12,7 +12,6 @@ &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.intel; - &tm-attrib.sparc; &tm-attrib.sun; &tm-attrib.general; </legalnotice> @@ -301,7 +300,7 @@ <itemizedlist> <listitem> - <para><emphasis>Do not leave the <quote>Synopsis</quote> + <para><emphasis>Do not leave the <quote>Summary</quote> line empty.</emphasis> The PRs go both onto a mailing list that goes all over the world (where the <quote>Synopsis</quote> is used for the @@ -375,13 +374,11 @@ <listitem> <para>Include which global options you have specified in - your <filename>make.conf</filename>. Note: specifying - <literal>-O2</literal> and above to &man.gcc.1; is - known to be buggy in many situations. While the &os; - developers will accept patches, they are generally - unwilling to investigate such issues due to simple - lack of time and volunteers, and may instead respond - that this just is not supported.</para> + your <filename>make.conf</filename>, + <filename>src.conf</filename>, + and <filename>src-env.conf</filename>. + Given the infinite number of options, not every + combination may be fully supported.</para> </listitem> <listitem> @@ -594,84 +591,24 @@ </section> <section xml:id="pr-writing-filling-template"> - <title>Filling out the Template</title> + <title>Filling out the Form</title> - <para>In the email template only, you will find the following - single-line fields:</para> + <note> + <para>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.</para> + </note> - <itemizedlist> - <listitem> - <para><emphasis>Submitter-Id:</emphasis> Do not change this. - The default value of <literal>current-users</literal> is - correct, even if you run &os.stable;.</para> - </listitem> + <para>When you file a bug, you will find the following + fields:</para> - <listitem> - <para><emphasis>Confidential:</emphasis> This is prefilled - to <literal>no</literal>. Changing it makes no sense as - there is no such thing as a confidential &os; problem - report—the PR database is distributed - worldwide.</para> - </listitem> - - <listitem> - <para><emphasis>Severity:</emphasis> One of - <literal>non-critical</literal>, - <literal>serious</literal> or <literal>critical</literal>. - Do not overreact; refrain from labeling your problem - <literal>critical</literal> unless it really is (e.g., - data corruption issues, serious regression from previous - functionality in -CURRENT) or <literal>serious</literal> - 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 - necessarily 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 because of this.</para> - </listitem> - - <listitem> - <para><emphasis>Priority:</emphasis> This field indicates - how widespread the effects of this bug is likely to - be.</para> - </listitem> - - - </itemizedlist> - - <para>The next section describes fields that are common to both - the email interface and the - <link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web - interface</link>:</para> - <itemizedlist> <listitem> - <para><emphasis>Originator:</emphasis> Please specify your - real name, optionally followed by your email address in - angle brackets. In the email interface, this is normally - prefilled with the <literal>gecos</literal> field of the - currently logged-in user.</para> - - <note> - <para>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.</para> - </note> - </listitem> - - <listitem> - <para><emphasis>Organization:</emphasis> Whatever you feel - like. This field is not used for anything - significant.</para> - </listitem> - - <listitem> - <para><emphasis>Synopsis:</emphasis> Fill this out with a + <para><emphasis>Summary:</emphasis> Fill this out with a short and accurate description of the problem. The synopsis is used as the subject of the problem report email, and is used in problem report listings and @@ -683,11 +620,23 @@ <literal>[patch]</literal> (including the brackets); if this is a ports PR and you are the maintainer, you may consider adding <literal>[maintainer update]</literal> - (including the brackets) and set the <quote>Class</quote> - of your PR to <literal>maintainer-update</literal>.</para> + (including the brackets).</para> </listitem> <listitem> + <para><emphasis>Severity:</emphasis> One of + <literal>Affects only me</literal>, + <literal>Affcts some people</literal> or <literal>Affects + many people</literal>. + Do not overreact; refrain from labeling your problem + <literal>Affects many people</literal> unless it really + does. &os; developers will not + necessarily work on your problem faster if you inflate its + importance since there are so many other people who have + done exactly that.</para> + </listitem> + + <listitem> <para><emphasis>Category:</emphasis> Choose an appropriate category.</para> @@ -735,11 +684,8 @@ <filename class="directory">/sbin</filename>, or <filename class="directory">/usr/sbin</filename>, it is part of the base system, and you should use the - <literal>bin</literal> category. (A few programs, - such as &man.gcc.1;, actually use the - <literal>gnu</literal> category, but do not worry - about that for now.) These are all things that are - described in section 1 or 8 of the manual + <literal>bin</literal> category. These are all things + that are described in section 1 or 8 of the manual pages.</para> </listitem> @@ -754,16 +700,9 @@ <listitem> <para>If you have found a problem in the documentation - set (articles, books, man pages), the correct choice - is <literal>docs</literal>.</para> - </listitem> + set (articles, books, man pages) or website the + correct choice is<literal>docs</literal>.</para> - <listitem> - <para>If you are having a problem with the <link - xlink:href="http://www.FreeBSD.org">FreeBSD web - pages</link>, the proper choice is - <literal>www</literal>.</para> - <note> <para>if you are having a problem with something from a port named @@ -799,19 +738,6 @@ </listitem> <listitem> - <para>If the problem has to do with errors internal to a - &java.virtual.machine; (&jvm;), even though &java; was - installed from the Ports Collection, you should select - the <literal>java</literal> category. More general - problems with &java; ports still go under - <literal>ports</literal>.</para> - </listitem> - </itemizedlist> - - <para>This leaves everything else.</para> - - <itemizedlist> - <listitem> <para>If you are convinced that the problem will only occur under the processor architecture you are using, select one of the architecture-specific categories: @@ -820,8 +746,8 @@ AMD machines running in 64-bit mode (this also includes Intel-compatible machines running in EMT64 mode); and less commonly <literal>arm</literal>, - <literal>ia64</literal>, <literal>powerpc</literal>, - and <literal>sparc64</literal>.</para> + <literal>ia64</literal>, and + <literal>powerpc</literal>.</para> <note> <para>These categories are quite often misused for @@ -862,161 +788,9 @@ choice.</para> </listitem> </itemizedlist> - - <para>Here is the current list of categories (taken from - <uri - xlink:href="https://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">https://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para>; - - <itemizedlist> - <listitem> - <para><literal>advocacy:</literal> problems relating to - &os;'s public image. Obsolete.</para> - </listitem> - - <listitem> - <para><literal>amd64:</literal> problems specific to the - AMD64 platform.</para> - </listitem> - - <listitem> - <para><literal>arm:</literal> problems specific to the - ARM platform.</para> - </listitem> - - <listitem> - <para><literal>bin:</literal> problems with userland - programs in the base system.</para> - </listitem> - - <listitem> - <para><literal>conf:</literal> problems with - configuration files, default values, and so - forth.</para> - </listitem> - - <listitem> - <para><literal>docs:</literal> problems with manual - pages or on-line documentation.</para> - </listitem> - - <listitem> - <para><literal>gnu:</literal> problems with imported GNU - software such as &man.gcc.1; or &man.grep.1;.</para> - </listitem> - - <listitem> - <para><literal>i386:</literal> problems specific to the - &i386; platform.</para> - </listitem> - - <listitem> - <para><literal>ia64:</literal> problems specific to the - ia64 platform.</para> - </listitem> - - <listitem> - <para><literal>java:</literal> problems related to the - &java; Virtual Machine.</para> - </listitem> - - <listitem> - <para><literal>kern:</literal> problems with - the kernel, (non-platform-specific) device drivers, - or the base libraries.</para> - </listitem> - - <listitem> - <para><literal>misc:</literal> anything that does not - fit 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 - <literal>HEAD</literal> do not belong here. Also note - that it is easy for things to get lost in this - category).</para> - </listitem> - - <listitem> - <para><literal>ports:</literal> problems relating to the - Ports Collection.</para> - </listitem> - - <listitem> - <para><literal>powerpc:</literal> problems specific to - the &powerpc; platform.</para> - </listitem> - - <listitem> - <para><literal>sparc64:</literal> problems specific to - the &sparc64; platform.</para> - </listitem> - - <listitem> - <para><literal>standards:</literal> standards - conformance issues.</para> - </listitem> - - <listitem> - <para><literal>threads:</literal> problems related to - the &os; threads implementation (especially on - &os.current;).</para> - </listitem> - - <listitem> - <para><literal>usb:</literal> problems related to the - &os; USB implementation.</para> - </listitem> - - <listitem> - <para><literal>www:</literal> changes or enhancements to - the &os; website.</para> - </listitem> - </itemizedlist> </listitem> <listitem> - <para><emphasis>Class:</emphasis> Choose one of the - following:</para> - - <itemizedlist> - <listitem> - <para><literal>sw-bug:</literal> software bugs.</para> - </listitem> - - <listitem> - <para><literal>doc-bug:</literal> errors in - documentation.</para> - </listitem> - - <listitem> - <para><literal>change-request:</literal> requests for - additional features or changes in existing - features.</para> - </listitem> - - <listitem> - <para><literal>update:</literal> updates to ports or - other contributed software.</para> - </listitem> - - <listitem> - <para><literal>maintainer-update:</literal> updates to - ports for which you are the maintainer.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Release:</emphasis> The version of &os; - that you are running. This - needs to be filled in.</para> - </listitem> - </itemizedlist> - - <para>Finally, there is a series of multi-line fields:</para> - - <itemizedlist> - <listitem> <para><emphasis>Environment:</emphasis> This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the @@ -1030,55 +804,19 @@ </listitem> <listitem> - <para><emphasis>Description:</emphasis> A complete and + <para><emphasis>Description:</emphasis>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.</para> - </listitem> - - <listitem> - <para><emphasis>How-To-Repeat:</emphasis> A summary of the - actions you need to take to reproduce the problem.</para> - </listitem> - - <listitem> - <para><emphasis>Fix:</emphasis> Preferably a patch, or at - least a workaround (which not only helps other people with + 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), but if - you do not have any firm ideas for either, it is better to - leave this field blank than to speculate.</para> + developer understand the cause for the problem.</para> </listitem> </itemizedlist> - </section> - - <section xml:id="pr-writing-sending"> - <title>Sending the Problem Report</title> - - <para>If you are using the <link - xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web form</link>:</para> - - <para>Before you hit <literal>submit</literal>, 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.</para> - - <para>Note that you are <literal>strongly advised</literal> to - save your work somewhere before hitting - <literal>submit</literal>. 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.</para> - - <para>If you are unable to view images for any reason, - please accept our - apologies for the inconvenience and email your problem report - to the bugbuster team at - <email>freebsd-bugbusters@FreeBSD.org</email>.</para> </section> </section>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808120846.w7C8kh1i027841>