The recent commit of my changes to the Porter's Handbook left some rough edges; this patch fixes them. First, some text was proposed but not accepted; there was some dangling text left behind that kind-of went with the rejected text. Next, some content that was added to replace existing content, or move it around, didn't have the original text deleted afterwards. Third, there are some places where a concept is introduced, then elaborated on, then the reason is given for having the concept. This patch switches those latter two around. Lastly, in a few places the language wound up being awkward. There is no new content in this patch; it's just a cleanup that IMHO makes the document "flow" a little bit better. How-To-Repeat: (n/a)
On Tue, Jan 20, 2004 at 04:47:28PM -0600, Mark Linimon wrote: Mark, Please commit this (with my approval), proviso the inline comments below. Thanks for following up on this. > @@ -348,8 +348,19 @@ > Also add a short description of the program you ported > to the <quote>Description</quote> field of the PR and > the shar or uuencoded tarfile to the > - <quote>Fix</quote> field. The latter one helps the committers > - a lot, who use scripts for the ports-work.</para> > + <quote>Fix</quote> field.</para> > + > + <note> > + <para>You can make our work a lot easier, if you use a good > + description in the synopsis of the problem report. > + We prefer something like > + <quote>New port: <category>/<portname> > + <short description of the port></quote> for new ports and > + <quote>Update port: <category>/<portname> > + <short description of the update></quote> for port updates. > + If you stick to this scheme, the chance that someone takes a > + look at your PR soon is much bigger.</para> s/someone takes/someone will take/, s/bigger/better/ (I can be swayed on the second - your call). > @@ -2793,7 +2793,9 @@ > <para>Set your mail-address here. Please. <!-- smiley > --><emphasis>:-)</emphasis></para> > > - <para>The format used should be <literal>user@hostname.domain</literal>. > + <para>Note that only a single address without comment part is > + allowed as a <makevar>MAINTAINER</makevar> value. > + The format used should be <literal>user@hostname.domain</literal>. s/without comment/the comment/ ? > @@ -4634,23 +4636,23 @@ > > <para>If the maintainer asks you to do the upgrade or the maintainer > is <literal>ports@FreeBSD.org</literal>, > - please make the upgrade and send the > + please make the upgrade and save the result of the > recursive <command>diff</command> output > of the new and old > - ports directories to us (e.g., if your modified port directory is > + ports directories. (e.g., if your modified port directory is There shouldn't be a period there. > called <filename>superedit</filename> and the original is in our tree > - as <filename>superedit.bak</filename>, then send us the result of > + as <filename>superedit.bak</filename>, then save the result of > <command>diff -ruN superedit.bak superedit</command>). Either > unified or context diff is fine, but port committers generally > prefer unified diffs. Note the use of the <literal>-N</literal> > option—this is the accepted way to force diff to properly > deal with the case of new files being added or old files being > - deleted.</para> > + deleted. Before sendingus the diff, please examine the > + output to make sure all the changes make sense.</para> s/sendingus/sending us/ Cheers, Ceri --
On Tue, Jan 20, 2004 at 03:10:16PM -0800, Ceri Davies wrote: > > @@ -2793,7 +2793,9 @@ > > <para>Set your mail-address here. Please. <!-- smiley > > --><emphasis>:-)</emphasis></para> > > =20 > > - <para>The format used should be <literal>user@hostname.domain</literal>. > > + <para>Note that only a single address without comment part is > > + allowed as a <makevar>MAINTAINER</makevar> value. > > + The format used should be <literal>user@hostname.domain</literal>. > > s/without comment/the comment/ ? Grr. s/without comment/without the comment/ Ceri --
State Changed From-To: open->closed Committed after review by ceri.