From owner-freebsd-doc@FreeBSD.ORG Fri May 9 00:27:04 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6BEC637B401 for ; Fri, 9 May 2003 00:27:04 -0700 (PDT) Received: from 21322530218.direct.eti.at (21322530218.direct.eti.at [213.225.30.218]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9E0D043FE0 for ; Fri, 9 May 2003 00:27:02 -0700 (PDT) (envelope-from tilman@arved.de) Received: from huckfinn.arved.de (localhost [127.0.0.1]) h497R1NM048572; Fri, 9 May 2003 09:27:01 +0200 (CEST) (envelope-from tilman@arved.de) Received: (from tilman@localhost) by huckfinn.arved.de (8.12.9/8.12.6/Submit) id h497R0aA048571; Fri, 9 May 2003 09:27:00 +0200 (CEST) X-Authentication-Warning: huckfinn.arved.de: tilman set sender to tilman@arved.de using -f Date: Fri, 9 May 2003 09:27:00 +0200 From: Tilman Linneweh To: Mark Linimon Message-ID: <20030509072659.GA48303@huckfinn.arved.de> References: <200305081851.41118.linimon@lonesome.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="ZPt4rx8FFjLCG7dd" Content-Disposition: inline In-Reply-To: <200305081851.41118.linimon@lonesome.com> User-Agent: Mutt/1.4.1i cc: freebsd-doc@FreeBSD.org Subject: Re: RFC: additions to the article "problem-reports" X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 May 2003 07:27:04 -0000 --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 > + > + Avoid using a weak Subject: line > + 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.) > + [..] 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 > + > + If you are a maintainer, say so > + By convention, if you are maintaining a part of the > + source code (for instance, a port), put the string > + [maintainer update] at the > + beginning of your Subject: line. > + 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--