From owner-freebsd-doc Thu Sep 28 17:16:58 2000 Delivered-To: freebsd-doc@freebsd.org Received: from ns1.sunesi.net (ns1.sunesi.net [196.15.192.194]) by hub.freebsd.org (Postfix) with ESMTP id 0429137B43E; Thu, 28 Sep 2000 17:15:42 -0700 (PDT) Received: from nbm by ns1.sunesi.net with local (Exim 3.03 #1) id 13enq0-000PbU-00; Fri, 29 Sep 2000 02:15:40 +0200 Date: Fri, 29 Sep 2000 02:15:39 +0200 From: Neil Blakey-Milner To: Mark Ovens Cc: Kris Kennaway , David O'Brien , doc@freebsd.org, ben@FreeBSD.org Subject: Re: Guidelines for new port version variables Message-ID: <20000929021539.A98318@mithrandr.moria.org> References: <20000928120954.C89733@dragon.nuxi.com> <20000928235603.C255@parish> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="mP3DRpeJDSE+ciuQ" X-Mailer: Mutt 1.0.1i In-Reply-To: <20000928235603.C255@parish>; from marko@freebsd.org on Thu, Sep 28, 2000 at 11:56:03PM +0100 Organization: Sunesi Clinical Systems X-Operating-System: FreeBSD 3.3-RELEASE i386 X-URL: http://rucus.ru.ac.za/~nbm/ Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --mP3DRpeJDSE+ciuQ Content-Type: text/plain; charset=us-ascii 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 --mP3DRpeJDSE+ciuQ Content-Type: text/plain; charset=us-ascii Content-Description: porters-handbook.portrevision.patch Content-Disposition: attachment; filename="porters-handbook.portrevision.patch" 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 @@ + <makevar>PORTREVISION</makevar> and + <makevar>PORTEPOCH</makevar> + + + <makevar>PORTREVISION</makevar> + + The PORTREVISION variable is a + monotonically increasing value which is reset to 0 with + every increase of PORTVERSION (i.e. + every time a new official vendor release is made), and + appended to the package name if non-zero. + PORTREVISION is increased each time a + change is made to the FreeBSD port which significantly + affects the content or stucture of the derived + package. + + Examples of when PORTREVISION should be bumped: + + + + Addition of patches to correct security + vulnerabilities, bugs, or to add new functionality to + the FreeBSD port. + + + + Changes to the port makefile to enable or disable + compile-time options in the package. + + + + 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). + + + + 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)). + + + + 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 + PORTVERSION, where a diff + -ru of the old and new versions shows + non-trivial changes to the code. + + + + Examples of changes which do not require a + PORTREVISION bump: + + + + Style changes to the port skeleton with no + functional change to what appears in the resulting + package. + + + + Changes to MASTER_SITES or + other functional changes to the port which do not + effect the resulting package. + + + + 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. + + + + 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 PORTREVISION reflects + the content of the package, if no package was + previously buildable then there is no need to increase + PORTREVISION to mark a + change. + + + + 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 + PORTREVISION should be bumped so that + automated tools (e.g. pkg_version) + will hilight the fact that a new package is + available. + + + + <makevar>PORTEPOCH</makevar> + + 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). + + In situations such as this, the + PORTEPOCH version should be increased. + If PORTEPOCH is nonzero it is appended + to the package name as described in section 0 above. + PORTEPOCH 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. + 1.0,1 in the above example) is still + numerically less than the previous version (2000801), but + the ,1 suffix is treated specially by + automated tools and found to be greater than the implied + suffix ",0" on the earlier package) + + It is expected that PORTEPOCH will + not be used for the majority of ports, and that sensible + use of PORTVERSION 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. + + 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 + PORTVERSION of 1.2.20000917 or similar, + not 20000917, so that the succeeding release, say 1.3, is + still a numerically greater value. + + + + Example of <makevar>PORTREVISION</makevar> and + <makevar>PORTEPOCH</makevar> usage + + The gtkmumble port, version 0.10, is committed to the + ports collection. + + +PORTNAME= gtkmumble +PORTVERSION= 0.10 + + PKGNAME becomes + gtkmumble-0.10. + + A security hole is discovered which requires a local + FreeBSD patch. PORTREVISION is bumped + accordingly. + + +PORTNAME= gtkmumble +PORTVERSIOn= 0.10 +PORTREVISION= 1 + + PKGNAME becomes + gtkmumble-0.10_1 + + A new version is released by the vendor, numbered 0.2 + (it turns out the author actually intended + 0.10 to actually mean + 0.1.0, not what comes after + 0.9 - oops, too late now). Since the new minor + version 2 is numerically less than the + previous version 10 the + PORTEPOCH must be bumped to manually + force the new package to be detected as "newer". Since it + is a new vendor release of the code, + PORTREVISION is reset to 0 (or removed + from the makefile). + + +PORTNAME= gtkmumble +PORTVERSION= 0.2 +PORTEPOCH= 1 + + PKGNAME becomes + gtkmumble-0.2,1 + + The next release is 0.3. Since + PORTEPOCH never decreases, the version + variables are now: + + +PORTNAME= gtkmumble +PORTVERSION= 0.3 +PORTEPOCH= 1 + + PKGNAME becomes + gtkmumble-0.3,1 + + Note that if PORTEPOCH were reset + to 0 with this upgrade, someone who had + installed the gtkmumble-0.10_1 package would not detect + the gtkmumble-0.3 package as newer, since + 3 is still numerically less than + 10. + + + + <makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar> Two optional variables, PKGNAMEPREFIX and --mP3DRpeJDSE+ciuQ-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message