docs/61653: [patch] cleanup after recent changes to Porter's Handbook
Mark Linimon
linimon at lonesome.com
Tue Jan 20 22:51:55 UTC 2004
>Number: 61653
>Category: docs
>Synopsis: [patch] cleanup after recent changes to Porter's Handbook
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue Jan 20 14:50:16 PST 2004
>Closed-Date:
>Last-Modified:
>Originator: Mark Linimon
>Release: FreeBSD 4.9-PRERELEASE i386
>Organization:
Lonesome Dove Computing Services
>Environment:
System: FreeBSD lonesome.lonesome.com 4.9-PRERELEASE FreeBSD 4.9-PRERELEASE #0: Fri Sep 5 01:19:33 CDT 2003 linimon at lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA_DEBUG i386
(n/a)
>Description:
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)
>Fix:
--- book.sgml.dist Tue Jan 20 16:33:11 2004
+++ book.sgml Tue Jan 20 16:33:16 2004
@@ -64,7 +64,7 @@
<chapter id="own-port">
<title>Making a port yourself</title>
- <para>So, you are still interested in making your own port or
+ <para>So, you are interested in making your own port or
upgrading an existing one? Great!</para>
<para>What follows are some guidelines for creating a new port for
@@ -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>
+ </note>
<para>One more time, <emphasis>do not include the original source
distfile, the <filename>work</filename> directory, or the package
@@ -375,18 +386,6 @@
<ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>
and other files. Isn't that great?!? <!-- smiley
-->:-)</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: <short description of the port></quote> for
- new ports and
- <quote>Update port: <category>/<port> <short description
- of the update></quote> for port updates.
- If you stick to this scheme, the chance that one takes a look at
- your PR soon is much bigger.</para>
- </note>
</sect1>
</chapter>
@@ -757,8 +756,13 @@
every increase of <makevar>PORTVERSION</makevar> (i.e.
every time a new official vendor release is made), and
appended to the package name if non-zero.
- <makevar>PORTREVISION</makevar> is increased each time a
- change is made to the FreeBSD port which significantly
+ Changes to <makevar>PORTREVISION</makevar> are
+ used by automated tools (e.g. &man.pkg.version.1;)
+ to highlight the fact that a new package is
+ available.</para>
+
+ <para><makevar>PORTREVISION</makevar> should be increased
+ each time a change is made to the port which significantly
affects the content or structure of the derived
package.</para>
@@ -769,7 +773,7 @@
<listitem>
<para>Addition of patches to correct security
vulnerabilities, bugs, or to add new functionality to
- the FreeBSD port.</para>
+ the port.</para>
</listitem>
<listitem>
@@ -832,7 +836,7 @@
the changes do not introduce any functional change on
any other platforms on which the port did previously
build). Since <makevar>PORTREVISION</makevar> reflects
- the content of the package, if no package was
+ the content of the package, if the package was not
previously buildable then there is no need to increase
<makevar>PORTREVISION</makevar> to mark a
change.</para>
@@ -846,10 +850,7 @@
actually work at all), and weigh that against that fact
that it will cause everyone who regularly updates their
ports tree to be compelled to update. If yes, the
- <makevar>PORTREVISION</makevar> should be bumped so that
- automated tools (e.g. &man.pkg.version.1;)
- will highlight the fact that a new package is
- available.</para>
+ <makevar>PORTREVISION</makevar> should be bumped.</para>
</sect3>
<sect3>
@@ -1577,7 +1578,7 @@
safely delete <literal>misc</literal> and just put the port
in that other subdirectory! If at all possible, try to
find a better category for your port than
- <literal>misc</literal> ports tend to get overlooked
+ <literal>misc</literal>, as ports tend to get overlooked
in here.</entry>
</row>
@@ -1814,8 +1815,7 @@
If your port <emphasis>is</emphasis> an X
application, define <makevar>USE_XLIB</makevar> (implied by
<makevar>USE_IMAKE</makevar>) and put it in the appropriate
- categories. Also, many of them go into other
- <filename>x11-*</filename> categories (see below).</entry>
+ category.</entry>
</row>
<row>
@@ -1938,7 +1938,7 @@
<para><makevar>DISTNAME</makevar> is the name of the port as
called by the authors of the software.
<makevar>DISTNAME</makevar> defaults to
- <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it if necessary.
+ <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it only if necessary.
<makevar>DISTNAME</makevar> is only used in two places.
First, the distribution file list
(<makevar>DISTFILES</makevar>) defaults to
@@ -1950,7 +1950,7 @@
<note>
<para><makevar>PKGNAMEPREFIX</makevar> and
<makevar>PKGNAMESUFFIX</makevar> do not affect
- <makevar>DISTNAME</makevar>. Also note that when
+ <makevar>DISTNAME</makevar>. Also note that if
<makevar>WRKSRC</makevar> is equal to
<filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
while the original source archive is named something other than
@@ -1997,7 +1997,7 @@
<para>These variables are defined in
<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
- new archives added all the time, so make sure to check the
+ new entries added all the time, so make sure to check the
latest version of this file before submitting a port.</para>
<para>The user can also set the <makevar>MASTER_SITE_*</makevar>
@@ -2793,7 +2793,9 @@
<para>Set your mail-address here. Please. <!-- smiley
--><emphasis>:-)</emphasis></para>
- <para>The format used should be <literal>user at 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 at hostname.domain</literal>.
Please do not include any descriptive text such as your real
name in this entry—that merely confuses
<filename>bsd.port.mk</filename>. Instead, put that information
@@ -2803,9 +2805,6 @@
refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
Makefiles</ulink> section.</para>
- <para>Note that only a single address without comment part is
- allowed as a <makevar>MAINTAINER</makevar> value.</para>
-
<para>If the maintainer of a port does not respond to an update
request from a user after two weeks (excluding major public
holidays), then that is considered a maintainer timeout, and the
@@ -3440,7 +3443,7 @@
package is not generally useful, and the application should always
be compiled from the source code. For example, if the application
has configuration information that is site specific hard coded in to
- it at compile time.</para>
+ it at compile time, set <makevar>NO_PACKAGE</makevar>.</para>
<para><makevar>NO_PACKAGE</makevar> should be set to a string
describing the reason why the package should not be
@@ -4547,7 +4549,7 @@
occurrences of <filename>/usr/local</filename> (or
<filename>/usr/X11R6</filename> for X ports that do not use imake)
in the various <filename>scripts/Makefile</filename>s in the port to read
- <makevar>PREFIX</makevar>, as this variable is automatically passed
+ <makevar>${PREFIX}</makevar>, as this variable is automatically passed
down to every stage of the build and install processes.</para>
<para>Make sure your application is not installing things in
@@ -4557,7 +4559,7 @@
<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>
<para>If anything is installed outside of <makevar>PREFIX</makevar>,
- making the package creation process will complain that it
+ the package creation process will complain that it
cannot find the files.</para>
<!-- XXX This paragraph is confusing and poorly indented. -->
@@ -4634,23 +4636,23 @@
<para>If the maintainer asks you to do the upgrade or the maintainer
is <literal>ports at 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
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>
- <para>Please examine
- the output to make sure all the changes make sense. The best way to
+ <para> The best way to
send us the diff is by including it via &man.send-pr.1; (category
- <literal>ports</literal>). If you are the maintainer for the port,
+ <literal>ports</literal>). If you are going to be the maintainer for the port,
be sure to put <literal>[maintainer update]</literal> at the beginning
of your synopsis line and/or set the <quote>Class</quote> of your PR
to <literal>maintainer-update</literal>. Please mention any added or
@@ -4676,8 +4678,8 @@
</important>
<note>
- <para>Once again, please use &man.diff.1; and not &man.shar.1; to send
- updates to existing ports!</para>
+ <para>Once again, please use &man.diff.1;, and not &man.shar.1;, to send
+ updates to existing ports!</para>
</note>
</chapter>
@@ -6397,8 +6399,8 @@
number of vulnerable FreeBSD hosts (we like being known
for being secure), however sometimes there is a
noticeable time gap between disclosure of a
- vulnerability and an updated software release of a piece
- of vulnerable software. Do not mark a port
+ vulnerability and an updated release of the
+ vulnerable software. Do not mark a port
<makevar>FORBIDDEN</makevar> for any reason other than
security.</para>
</listitem>
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list