Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 17 Sep 2000 02:25:14 -0700 (PDT)
From:      Kris Kennaway <kris@FreeBSD.org>
To:        committers@freebsd.org, doc@freebsd.org, ports@freebsd.org
Subject:   Guidelines for new port version variables
Message-ID:  <Pine.BSF.4.21.0009170222550.64618-100000@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help
Hi all,

This is a revised version of the original proposal document I sent to
-ports, which describes what the two new package version variables are
(PORTREVISION and PORTEPOCH) and how to use them.

All committers who maintain a port, or who intend to commit changes to one
should read this document and make an effort to use the new variables. Can
one of the doc guys commit this to the porters handbook?

Kris

====================================================================

FREEBSD PACKAGE VERSIONING CONVENTIONS

0) OVERVIEW

Packages names are constructed according to the following system:

${PORTNAME}-${PORTVERSION}[_${PORTREVISION}][,${PORTEPOCH}]

The older package naming system was simply ${PORTNAME}-${PORTVERSION}

The meaning of the two variables PORTREVISION and PORTEPOCH and the
rationale for their use are explained below.

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 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 -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 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.

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. 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.

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.

--
In God we Trust -- all others must submit an X.509 certificate.
    -- Charles Forsythe <forsythe@alum.mit.edu>



To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-ports" in the body of the message




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.4.21.0009170222550.64618-100000>