Date: Fri, 29 Sep 2000 02:15:39 +0200 From: Neil Blakey-Milner <nbm@mithrandr.moria.org> To: Mark Ovens <marko@freebsd.org> Cc: Kris Kennaway <kris@freebsd.org>, David O'Brien <obrien@freebsd.org>, doc@freebsd.org, ben@FreeBSD.org Subject: Re: Guidelines for new port version variables Message-ID: <20000929021539.A98318@mithrandr.moria.org> In-Reply-To: <20000928235603.C255@parish>; from marko@freebsd.org on Thu, Sep 28, 2000 at 11:56:03PM %2B0100 References: <20000928120954.C89733@dragon.nuxi.com> <Pine.BSF.4.21.0009281414080.66918-100000@freefall.freebsd.org> <20000928235603.C255@parish>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --]
On Thu 2000-09-28 (23:56), Mark Ovens wrote:
> > I need someone from the doc project to mark it up..I haven't heard
> > anything back however.
> >
>
> I'll do it. Please mail me a copy of the document that you are referring to.
Here's my quick-shot at it.
My brain isn't in docbook mode, so I probably misused or missed uses of
literal, quote, and so forth.
I'm pretty sure either Ben or Mark will remind me how this all works
again.
Neil
--
Neil Blakey-Milner
Sunesi Clinical Systems
nbm@mithrandr.moria.org
[-- Attachment #2 --]
Index: book.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO_8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.129
diff -u -r1.129 book.sgml
--- book.sgml 2000/09/24 07:01:53 1.129
+++ book.sgml 2000/09/29 00:04:58
@@ -675,6 +675,223 @@
</sect1>
<sect1>
+ <title><makevar>PORTREVISION</makevar> and
+ <makevar>PORTEPOCH</makevar></title>
+
+ <sect2>
+ <title><makevar>PORTREVISION</makevar></title>
+
+ <para>The <makevar>PORTREVISION</makevar> variable is a
+ monotonically increasing value which is reset to 0 with
+ 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
+ affects the content or stucture of the derived
+ package.</para>
+
+ <para>Examples of when PORTREVISION should be bumped:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Addition of patches to correct security
+ vulnerabilities, bugs, or to add new functionality to
+ the FreeBSD port.</para>
+ </listitem>
+
+ <listitem>
+ <para>Changes to the port makefile to enable or disable
+ compile-time options in the package.</para>
+ </listitem>
+
+ <listitem>
+ <para>Changes in the packing list or the install-time
+ behaviour of the package (e.g. change to a script
+ which generates initial data for the package, like ssh
+ host keys).</para>
+ </listitem>
+
+ <listitem>
+ <para>Version bump of a port's shared library dependency
+ (in this case, someone trying to install the old
+ package after installing a newer version of the
+ dependency will fail since it will look for the old
+ libfoo.x instead of libfoo.(x+1)).</para>
+ </listitem>
+
+ <listitem>
+ <para>Silent changes to the port distfile which have
+ significant functional differences, i.e. changes to
+ the distfile requiring a correction to files/md5 with
+ no corresponding change to
+ <makevar>PORTVERSION</makevar>, where a <command>diff
+ -ru</command> of the old and new versions shows
+ non-trivial changes to the code.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Examples of changes which do not require a
+ <makevar>PORTREVISION</makevar> bump:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Style changes to the port skeleton with no
+ functional change to what appears in the resulting
+ package.</para>
+ </listitem>
+
+ <listitem>
+ <para>Changes to <makevar>MASTER_SITES</makevar> or
+ other functional changes to the port which do not
+ effect the resulting package.</para>
+ </listitem>
+
+ <listitem>
+ <para>Trivial patches to the distfile such as correction
+ of typos, which are not important enough that users of
+ the package should go to the trouble of
+ upgrading.</para>
+ </listitem>
+
+ <listitem>
+ <para>Build fixes which cause a package to become
+ compilable where it was previously failing (as long as
+ 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
+ previously buildable then there is no need to increase
+ <makevar>PORTREVISION</makevar> to mark a
+ change.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A rule of thumb is to ask yourself whether a change
+ committed to a port is something which someone, somewhere,
+ would benefit from having (either because of an
+ enhancement, fix, or by virtue that the new package will
+ actually work for them). If yes, the
+ <makevar>PORTREVISION</makevar> should be bumped so that
+ automated tools (e.g. <command>pkg_version</command>)
+ will hilight the fact that a new package is
+ available.</para>
+ </sect2>
+
+ <sect2>
+ <title><makevar>PORTEPOCH</makevar></title>
+
+ <para>From time to time a software vendor or FreeBSD porter
+ will do something silly and release a version of their
+ software which is actually numerically less than the
+ previous version. An example of this is a port which goes
+ from foo-20000801 to foo-1.0 (the former will be
+ incorrectly treated as a newer version since 20000801 is a
+ numerically greater value than 1).</para>
+
+ <para>In situations such as this, the
+ <makevar>PORTEPOCH</makevar> version should be increased.
+ If <makevar>PORTEPOCH</makevar> is nonzero it is appended
+ to the package name as described in section 0 above.
+ <makevar>PORTEPOCH</makevar> is never decreased or reset
+ to zero, because that would cause comparison to a package
+ from an earlier epoch to fail (i.e. the package would not
+ be detected as out of date): the new version number (e.g.
+ <literal>1.0,1</literal> in the above example) is still
+ numerically less than the previous version (2000801), but
+ the <literal>,1</literal> suffix is treated specially by
+ automated tools and found to be greater than the implied
+ suffix ",0" on the earlier package)</para>
+
+ <para>It is expected that <makevar>PORTEPOCH</makevar> will
+ not be used for the majority of ports, and that sensible
+ use of <makevar>PORTVERSION</makevar> can often pre-empt
+ it becoming necessary if a future release of the software
+ should change the version structure. However, care is
+ needed by FreeBSD porters when a vendor release is made
+ without an official version number - such as a code
+ "snapshot" release. The temptation is to label the
+ release with the release date, which will cause problems
+ as in the example above when a new "official" release is
+ made.</para>
+
+ <para>For example, if a snapshot release is made on the date
+ 20000917, and the previous version of the software was
+ version 1.2, the snapshot release should be given a
+ <makevar>PORTVERSION</makevar> of 1.2.20000917 or similar,
+ not 20000917, so that the succeeding release, say 1.3, is
+ still a numerically greater value.</para>
+ </sect2>
+
+ <sect2>
+ <title>Example of <makevar>PORTREVISION</makevar> and
+ <makevar>PORTEPOCH</makevar> usage</title>
+
+ <para>The gtkmumble port, version 0.10, is committed to the
+ ports collection.</para>
+
+ <programlisting>
+PORTNAME= gtkmumble
+PORTVERSION= 0.10</programlisting>
+
+ <para><makevar>PKGNAME</makevar> becomes
+ <literal>gtkmumble-0.10</literal>.</para>
+
+ <para>A security hole is discovered which requires a local
+ FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped
+ accordingly.</para>
+
+ <programlisting>
+PORTNAME= gtkmumble
+PORTVERSIOn= 0.10
+PORTREVISION= 1</programlisting>
+
+ <para><makevar>PKGNAME</makevar> becomes
+ <literal>gtkmumble-0.10_1</literal></para>
+
+ <para>A new version is released by the vendor, numbered 0.2
+ (it turns out the author actually intended
+ <literal>0.10</literal> to actually mean
+ <literal>0.1.0</literal>, not <quote>what comes after
+ 0.9</quote> - oops, too late now). Since the new minor
+ version <literal>2</literal> is numerically less than the
+ previous version <literal>10</literal> the
+ <makevar>PORTEPOCH</makevar> must be bumped to manually
+ force the new package to be detected as "newer". Since it
+ is a new vendor release of the code,
+ <makevar>PORTREVISION</makevar> is reset to 0 (or removed
+ from the makefile).</para>
+
+ <programlisting>
+PORTNAME= gtkmumble
+PORTVERSION= 0.2
+PORTEPOCH= 1</programlisting>
+
+ <para><makevar>PKGNAME</makevar> becomes
+ <literal>gtkmumble-0.2,1</literal></para>
+
+ <para>The next release is 0.3. Since
+ <makevar>PORTEPOCH</makevar> never decreases, the version
+ variables are now:</para>
+
+ <programlisting>
+PORTNAME= gtkmumble
+PORTVERSION= 0.3
+PORTEPOCH= 1</programlisting>
+
+ <para><makevar>PKGNAME</makevar> becomes
+ <literal>gtkmumble-0.3,1</literal></para>
+
+ <para>Note that if <makevar>PORTEPOCH</makevar> were reset
+ to <literal>0</literal> with this upgrade, someone who had
+ installed the gtkmumble-0.10_1 package would not detect
+ the gtkmumble-0.3 package as newer, since
+ <literal>3</literal> is still numerically less than
+ <literal>10</literal>.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
<title><makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar></title>
<para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> and
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000929021539.A98318>