os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add text about handling unassigned PRs.

Browse source 
Add text about default assignees and common assignees (specifically
   to address the continuing confusion about assigning to mailing lists
   vs. assigning to aliases).
Add more text about how misfiled PRs occur.
Add more text about how to kill spam PRs.

Discussed on:	freebsd-doc
Reviewed by:	mheinen, ceri
This commit is contained in:
Mark Linimon 2004-11-30 08:51:52 +00:00
parent aae93d1789
commit 4183982aac
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=23076
1 changed files with 246 additions and 5 deletions

251
en_US.ISO8859-1/articles/pr-guidelines/article.sgml
View file

@ -232,6 +232,9 @@
different types of PRs.</para>
<itemizedlist>
<listitem>
<para><link linkend="pr-unassigned">PRs not yet assigned to anyone.</link></para>
</listitem>
<listitem>
<para><link linkend="pr-assigned">PRs already assigned to someone.</link></para>
</listitem>
@ -250,6 +253,203 @@
PRs is used for, when a PR belongs to one of these types, and what
treatment each different type receives.</para>
<section id="pr-unassigned">
<title>Unassigned PRs</title>
<para>When PRs arrive, they are initially assigned to a generic
(placeholder) assignee. These are always prepended with
<literal>freebsd-</literal>. The exact value for this default
depends on the category; in most cases, it corresponds to a
specific &os; mailing list. Here are some examples:</para>
<table id=default-assignees>
<title>Default Assignees</title>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Categories</entry>
<entry>Default Assignee</entry>
</row>
</thead>
<tbody>
<row>
<entry>base system</entry>
<entry>bin, conf, gnu, kern, misc</entry>
<entry>freebsd-bugs</entry>
</row>
<row>
<entry>architecture-specific</entry>
<entry>alpha, i386, ia64, powerpc, sparc64</entry>
<entry>freebsd-<replaceable>arch</replaceable></entry>
</row>
<row>
<entry>ports collection</entry>
<entry>ports</entry>
<entry>freebsd-ports-bugs</entry>
</row>
<row>
<entry>documentation shipped with the system</entry>
<entry>docs</entry>
<entry>freebsd-doc</entry>
</row>
<row>
<entry>&os; web pages (not including docs)</entry>
<entry>www</entry>
<entry>freebsd-www</entry>
</row>
<row>
<entry>standards compliance</entry>
<entry>standards</entry>
<entry>freebsd-standards</entry>
</row>
<row>
<entry>JVM problems</entry>
<entry>java</entry>
<entry>freebsd-java</entry>
</row>
<row>
<entry>advocacy efforts</entry>
<entry>advocacy</entry>
<entry>freebsd-advocacy</entry>
</row>
</tbody>
</table>
<para>Do not be surprised to find that the submitter of the
PR has assigned it to the wrong category. If you fix the
category, do not forget to fix the assignment as well.
(In particular, our submitters seem to have a hard time
understanding that just because their problem manifested
on an i386 system, that it might be generic to all of &os;,
and thus be more appropriate for <literal>kern</literal>.
The converse is also true, of course.)</para>
<para>Certain PRs may be reassigned away from these generic
assignees by anyone. For assignees which are mailing lists,
please use the long form when making the assignment (e.g.,
<literal>freebsd-foo</literal> instead of <literal>foo</literal>);
this will avoid duplicate emails sent to the mailing list.</para>
<note>
<para>Here is a sample list of such entities; it is probably
not complete. Entries that have the short form are
<emphasis>aliases</emphasis>, not mailing lists.</para>
</note>
<table id=common-assignees>
<title>Common Assignees</title>
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Suggested Assignee</entry>
</row>
</thead>
<tbody>
<row>
<entry>problem with Linux or SVR4 emulation</entry>
<entry>emulation</entry>
</row>
<row>
<entry>problem with the networking stack</entry>
<entry>freebsd-net</entry>
</row>
<row>
<entry>problem with PicoBSD</entry>
<entry>freebsd-small</entry>
</row>
<row>
<entry>problem with the ports framework
(<emphasis>not</emphasis> with an individual port!)</entry>
<entry>portmgr</entry>
</row>
<row>
<entry>problem with the SCSI subsystem</entry>
<entry>freebsd-scsi</entry>
</row>
<row>
<entry>problem with the sound subsystem</entry>
<entry>sound</entry>
</row>
<row>
<entry>problem with the threads subsystem</entry>
<entry>freebsd-threads</entry>
</row>
<row>
<entry>problem with <application>sysinstall</application></entry>
<entry>freebsd-qa</entry>
</row>
<row>
<entry>problem with the USB subsystem</entry>
<entry>freebsd-usb</entry>
</row>
<row>
<entry>port which is maintained by gnome@FreeBSD.org</entry>
<entry>gnome</entry>
</row>
<row>
<entry>port which is maintained by haskell@FreeBSD.org</entry>
<entry>haskell</entry>
</row>
<row>
<entry>port which is maintained by kde@FreeBSD.org</entry>
<entry>kde</entry>
</row>
<row>
<entry>port which is maintained by
openoffice@FreeBSD.org</entry>
<entry>freebsd-openoffice</entry>
</row>
<row>
<entry>port which is maintained by perl@FreeBSD.org</entry>
<entry>freebsd-perl</entry>
</row>
<row>
<entry>port which is maintained by x11@FreeBSD.org</entry>
<entry>freebsd-x11</entry>
</row>
</tbody>
</table>
<para>Ports PRs which have a maintainer who is a ports committer
may be reassigned by anyone (but note that not every &os;
committer is necessarily a ports committer, so you cannot
simply go by the email address alone.)
</para>
<para>For other PRs, please do not reassign them to individuals
(other than yourself) unless you are certain that the assignee
really wants to track the PR. This will help to avoid the
case where no one looks at fixing a particular problem
because everyone assumes that the assignee is already working
on it.</para>
</section>
<section id="pr-assigned">
<title>Assigned PRs</title>
@ -366,12 +566,29 @@
header.</para>
</listitem>
<listitem>
<para>A submitter sent a Cc: to a mailing list and someone
followed up to that post instead of the email issued by
GNATS after processing. The email to the list will not
have the category/PRnumber tracking tag. (This is why we
discourage submitters from doing this exact thing.)</para>
</listitem>
<listitem>
<para>When completing the &man.send-pr.1; template, the submitter
forgot to set the category or class of the PR to a proper
value.</para>
</listitem>
<listitem>
<para>When completing the &man.send-pr.1; template, the submitter
set Confidential to <literal>yes</literal>. (Since we allow
anyone to mirror GNATS via <application>cvsup</application>,
our PRs are public information. Security alerts should
therefore not be sent via GNATS but instead via email to
the Security Team.)</para>
</listitem>
<listitem>
<para>It is not a real PR, but some random message sent to
<email>bug-followup@FreeBSD.org</email> or
@ -487,8 +704,8 @@ This was misfiled because the subject didn't have the format:
<para>The email addresses that GNATS listens to for incoming PRs
have been published as part of the FreeBSD documentation, have
been announced and listed on the web-site. This means that
spammers found them. Every day several messages with
advertisements would reach GNATS which promptly files them all
spammers found them. Spam messages
that reach GNATS are promptly filed
under the <quote>pending</quote> category until someone looks
at them. Closing one of these with &man.edit-pr.1; is very
annoying though, because GNATS replies to the submitter and
@ -503,11 +720,35 @@ This was misfiled because the subject didn't have the format:
<para>All developers who have access to the FreeBSD.org cluster
machines are encouraged to check for misfiled PRs and immediately
close those that are spam mail. Whenever you close one of
these PRs it is also a good idea to set its category to
<quote><literal>junk</literal></quote>. Junk PRs are not
these PRs, please do the following:
<itemizedlist>
<listitem>
<para>Set Category to <literal>junk</literal>.</para>
</listitem>
<listitem>
<para>Set Confidential to <literal>no</literal>.</para>
</listitem>
<listitem>
<para>Set Responsible to yourself (and not, e.g.,
<literal>freebsd-bugs</literal>, which merely
sends more mail).</para>
</listitem>
<listitem>
<para>Set State to <literal>closed</literal>.</para>
</listitem>
</itemizedlist>
<para>Junk PRs are not
backed up, so filing spam mail under this category makes it
obvious that we do not care to keep it around or waste disk
space for it.</para>
space for it. If you merely close them without changing the
category, they remain both in the master database and in
any copies of the database mirrored through
<application>cvsup</application>.</para>
</section>
</section>
</section>