RFC: additions to the article "problem-reports"

[Tilman Linneweh]

Nice work! Comments below.

* Mark Linimon [Fr, 09 Mai 2003 at 01:48 GMT]:
> While working on my project to classify ports PRs in the database,
> I've come across more than my fair share of PRs that are really
> badly written.  Although the problem-reports article touches on
> this to some degree, I really feel that some of the most obvious
> mistakes bear further explanation.
> 
[..]
> --- article.sgml.dist	Thu May  8 17:16:29 2003
> +++ article.sgml	Thu May  8 18:44:42 2003
> +	<listitem>
> +	  <para><emphasis>Avoid using a weak Subject: line</emphasis>
> +            You should not assume that anyone reading your PR has
> +            any context for your submission: what part of the system
> +            does the problem apply to?  Do you only see the problem
> +            while installing, or while running?  So, instead of saying,
> +            for instance, "Subject: portupgrade is broken", say,
> +            "Subject: port sysutils/portupgrade coredumps on
> +            -current".  (In the case of ports, it is especially
> +            helpful to have both the category and portname in
> +            the Subject line.)</para>
> +        </listitem>
[..]

Well in this example the portname is already in the subject. Often PRs
mention a program foo in the Subject that is installed by a port named bar, 
e.g. pkgdb, which is installed by portupgrade. Real world example: ports/40218 

> +      
> +	<listitem>
> +	  <para><emphasis>If you are a maintainer, say so</emphasis>
> +            By convention, if you are maintaining a part of the
> +            source code (for instance, a port), put the string
> +            <literal>[maintainer update]</listeral> at the
> +            beginning of your Subject: line.</para>
> +        </listitem>

Not necessary, IMHO, there is a seperate "Class: " where you can mark your
PR as "maintainer-update"


regards
tilman
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030509/2de46c08/attachment.sig>