Date: Fri, 9 May 2003 09:27:00 +0200 From: Tilman Linneweh <tilman@arved.de> To: Mark Linimon <linimon@lonesome.com> Cc: freebsd-doc@FreeBSD.org Subject: Re: RFC: additions to the article "problem-reports" Message-ID: <20030509072659.GA48303@huckfinn.arved.de> In-Reply-To: <200305081851.41118.linimon@lonesome.com> References: <200305081851.41118.linimon@lonesome.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--ZPt4rx8FFjLCG7dd Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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. >=20 [..] > --- 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,= =20 e.g. pkgdb, which is installed by portupgrade. Real world example: ports/40= 218=20 > + =20 > + <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 --ZPt4rx8FFjLCG7dd Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+u1hCfCLDn4B6xToRAj3LAJ9gHdgpFLRAXB9Lr3+dI8L2WVzjMgCePP92 mfnnqb9o0hqDvgxYlPF1m4I= =TtTg -----END PGP SIGNATURE----- --ZPt4rx8FFjLCG7dd--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030509072659.GA48303>