Die PORTREVISION-Variable ist ein streng monoton wachsender Wert, welcher auf 0 zurückgesetzt wird, nachdem PORTVERSION erhöht wurde (d.h. jedes Mal, wenn ein offizielles Release erfolgt). Sie wird an den Namen des Pakets angehängt, wenn sie ungleich 0 ist. Änderungen an PORTREVISION werden von automatisierten Werkzeugen (z.B. pkg_version(1)) genutzt, um anzuzeigen, dass ein neues Paket verfügbar ist.

PORTREVISION sollte jedes Mal erhöht werden, wenn eine Änderung am Port erfolgt, die beträchtliche Auswirkungen auf den Inhalt oder Struktur des aus dem Port erzeugten Pakets zur Folge hat.

Beispiele dafür, wann PORTREVISION erhöht werden sollte:

Beispiele für Änderungen, welche keine Erhöhung von PORTREVISION erfordern:

Als Faustregel gilt: Stellen Sie sich die Frage, ob die durchgeführte Änderung am Port jedem hilft (entweder aufgrund einer Verbesserung, Beseitigung eines Fehlers, oder der Annahme, dass das neue Paket überhaupt erst funktioniert) und wägen Sie es gegen den Umstand ab, dass jedermann, der seine Ports-Sammlung regelmässig auf dem neuesten Stand hält, zu einer Aktualisierung gezwungen wird. Falls Sie die Frage positiv beantworten sollten, erhöhen Sie die Variable PORTREVISION.

Von Zeit zu Zeit geschieht es, dass irgendjemand (Drittanbieter von Software oder FreeBSD Ports Committer) etwas Dummes tut und eine Version einer Software veröffentlicht, deren Versionsnummer niedriger ist als die der vorherigen. Ein Beispiel hierfür ist ein Port, der von foo-20000801 auf foo-1.0 geändert wird (der Erstere wird fälschlicherweise als neue Version behandelt, weil 2000801 ein numerisch größerer Wert ist als 1).

In Situationen wie diesen sollte die Variable PORTEPOCH erhöht werden. Wenn PORTEPOCH größer als 0 ist, wird sie an den Namen des Pakets angehängt, wie in Abschnitt 0 oberhalb bereits beschrieben. PORTEPOCH darf niemals verringert oder auf 0 gesetzt werden, weil der Vergleich des Pakets mit einem früheren Zeitpunkt scheitern würde (d.h. das Paket würde niemals als veraltet erkannt werden): Die neue Versionsnummer (1.0,1 im obigen Beispiel) ist immer noch numerisch kleiner als die vorherige Version (2000801), aber das Suffix ,1 wird von automatisierten Werkzeugen gesondert behandelt und wird als größer erkannt, als das implizit angenommene Suffix ,0 im früheren Paket.

Das Entfernen oder Zurücksetzen von PORTEPOCH führt zu unendlichem Ärger. Wenn Sie die obigen Ausführungen nicht vollständig verstanden haben, lesen Sie es bitte unbedingt nochmals bis Sie es vollständig verinnerlicht haben, oder fragen Sie vor jeder Änderung auf den Mailinglisten nach!

Es wird erwartet, dass PORTEPOCH für die weitaus überwiegende Zahl der Ports nicht verwendet wird und der verantwortungsvolle und vorausschauende Umgang mit PORTVERSION macht es meist überflüssig, falls ein späteres Release die Versionsstruktur ändern sollte. Vorsicht ist geboten, wenn ein Release einer Drittanbieter-Software ohne eine offizielle Versionsnummer veröffentlicht wird, wie z.B. bei „Snapshot-Versionen“. Man ist versucht, das Release mit dem jeweiligen Datum zu bezeichnen, was unweigerlich zu den oben beschriebenen Problemen führt, wenn das nächste „offizielle“ Release erscheint.

Wenn z.B. ein Snapshot zum Datum 20000917 veröffentlicht wird und die vorherige Version der Software war 1.2, dann sollte der Snapshot die PORTVERSION 1.2.20000917 oder ähnlich erhalten und nicht 20000917, damit das nachfolgende Release, angenommen 1.3, immer noch einen größeren numerischen Wert aufweist.

Der gtkmumble-Port, Version 0.10, befindet sich in der Ports-Sammlung:

PORTNAME=       gtkmumble
PORTVERSION=    0.10

PKGNAME wird zu gtkmumble-0.10.

Ein Sicherheitsloch wurde entdeckt, das einen lokalen Patch von FreeBSD erforderlich macht. PORTREVISION wird entsprechend erhöht.

PORTNAME=       gtkmumble
PORTVERSION=    0.10
PORTREVISION=   1

PKGNAME wird zu gtkmumble-0.10_1

Eine neue Version wird vom Software-Drittanbieter veröffentlicht, bezeichnet mit der Version 0.2 (es stellt sich heraus, dass der Autor beabsichtigte, dass 0.10 eigentlich 0.1.0 bedeuten sollte, nicht „was kommt nach 0.9“  – Hoppla, aber nun ist es zu spät). Da die neue Unterversion 2 numerisch kleiner ist als die vorherige Version 10, muss PORTEPOCH erhöht werden, um sicherzustellen, dass das neue Paket auch als „neuer“ erkannt wird. Da es ein neues Release des Drittanbieters ist, wird PORTREVISION auf 0 zurückgesetzt (oder aus dem Makefile entfernt).

PORTNAME=       gtkmumble
PORTVERSION=    0.2
PORTEPOCH=      1

PKGNAME wird zu gtkmumble-0.2,1

Das nächste Release ist 0.3. Da PORTEPOCH niemals verringert wird, sind die Versionsvariablen nun wie folgt:

PORTNAME=       gtkmumble
PORTVERSION=    0.3
PORTEPOCH=      1

PKGNAME wird zu gtkmumble-0.3,1