From owner-freebsd-ports Sun Aug 20 4:35:54 2000 Delivered-To: freebsd-ports@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 921D437B42C for ; Sun, 20 Aug 2000 04:35:50 -0700 (PDT) Received: from localhost (kris@localhost) by freefall.freebsd.org (8.9.3/8.9.2) with ESMTP id EAA24475 for ; Sun, 20 Aug 2000 04:35:50 -0700 (PDT) (envelope-from kris@FreeBSD.org) X-Authentication-Warning: freefall.freebsd.org: kris owned process doing -bs Date: Sun, 20 Aug 2000 04:35:50 -0700 (PDT) From: Kris Kennaway To: ports@freebsd.org Subject: Proposal: PORTREVISION and PORTEPOCH Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-ports@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org PROPOSAL FOR PACKAGE NAMING CONVENTIONS 0) EXECUTIVE SUMMARY The current versioning scheme for packages built from FreeBSD ports is insufficient to convey all the information about the port it is based on, since it doesn't reflect FreeBSD-specific patches/fixes/alterations made to the generating port. The proposal is that we adopt two new version numbers: PORTREVISION and PORTEPOCH which are used to construct the package name as follows: ${PORTNAME}-${PORTVERSION}[_${PORTREVISION}][:${PORTEPOCH}] compared to the current system of: ${PORTNAME}-${PORTVERSION} 1) PORTREVISION 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 * 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 -ruN 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 it does * 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. 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. 2) PORTEPOCH 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. 3) EXAMPLE 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". 4) BENEFITS There are three main benefits to a more granular naming scheme: * Finer control over external references to packages. For example, when a security fix is made to the port, and PORTREVISION is increased accordinging, the relevant security advisory can point unambigiously to the new package name, instead of referring vaguely to "packages dated after the correction date", which is ambiguous and error-prone. * The ability for end-users to tell when a significant change has been made to the FreeBSD version of a port, and to unambiguously detect newer versions of the package (the current version is error-prone due to the lack of PORTEPOCH) * It lays the foundation for future automated upgrade systems, which can rebuild complex dependency chains of packages when changes are made. 5) IMPACT These changes should not require modification of the existing port/package infrastructure beyond the trivial change to bsd.port.mk to generate the new names, and changes to pkg_version (and other tools, if they exist), to make full use of the new format. In particular, the new format should be completely backwards-compatible with old tools (i.e. they will work as well as before), while allowing future improvements to provide increased functionality. -- In God we Trust -- all others must submit an X.509 certificate. -- Charles Forsythe To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-ports" in the body of the message