4.3. PORTREVISION and PORTEPOCH

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

Examples of changes which do not require a PORTREVISION bump:

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 highlight the fact that a new package is available.

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

4.3.3. Example of PORTREVISION and PORTEPOCH 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: 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.

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.