PORTREVISION 変数は単調増加する値です. PORTVERSION が増加した時 (つまり, 新しいオフィシャルベンダーリリースが行なわれた時) には いつでも 0 にリセットされます. また, その値が 0 でない場合には package 名に追加されます. その port から作られる package の内容や構造に 大きな影響を与える変更を行なった時には, PORTREVISION を増やしてください.
PORTREVISION を上げる必要がある変更の例:
セキュリティ上の脆弱性やバグを修正するため, または その port に新しい機能性を追加するためのパッチの追加.
package のコンパイル時オプションの有効化や 無効化のための Makefile の変更.
パッキングリストの変更や, package のインストール時の 挙動の変更 (たとえば, ssh のホストキーのような package の 初期データを生成するスクリプトの変更など).
その port が依存する共有ライブラリのバージョンを 上げる場合 (新しいバージョンの共有ライブラリが インストールされた後に, そのライブラリに依存していた 古い package をインストールを試みる場合, その package は新しい libfoo.(x+1) ではなく 古い libfoo.x を探そうとするため, インストールに失敗します. (訳注: そのため, PORTREVISION を上げた package を 作成する必要があるわけです)).
ひそかに port 配布ファイルの変更が行なわれ, その機能に大きな変化があった場合. つまり, distinfo の修正を 必要とするような配布ファイルの変更が行なわれ, 新旧のバージョンの diff -ru を取ると 些細とは言えない変更が認められるにもかかわらず, オリジナルのバージョン番号が変更されていないことから PORTVERSION の変更は難しい場合.
PORTREVISION を上げる必要の無い変更の例:
生成される package に機能の変化が起らないような port スケルトンのスタイル変更.
生成される package に影響しないような MASTER_SITES その他の port に対する機能変更.
誤植の修正などの些細な変更で, その package のユーザが アップグレードを必要とするほどには重要でないパッチ.
以前にはコンパイルが通らなかった package を ビルド可能にするための修正 (その port が以前にビルド可能だった プラットフォームにおいて, その変更により何らかの機能的な 違いが発生しない場合に限ります). PORTREVISION は package の内容を 反映したものなので, その package が以前にビルド可能でなければ 内容の変更も無いため, PORTREVISION を 増やす必要はありません.
経験的な判断方法としては, ある port にコミットされた変更が (それが強化や修正によるものであれ, 新しい package による 実質的な効能であれ), アップデートすることにより誰かがどこかで 利益を受けるような何か かどうか自問してみることです. もし答がイエスであれば, 新しい package が利用可能になった事実を (例えば pkg_version 等の) 自動化ツールが 強調することができるように, PORTREVISION を 上げるべきでしょう.
ソフトウェアのベンダや FreeBSD の port 作成者は, 以前のものよりも小さい数字のバージョン番号をつけたソフトウェアを リリースするといった, 何か馬鹿げたことをすることが時々あります. 例をあげると, ある port が foo-20000801 から foo-1.0 になる といった具合です (数字として見ると 20000801 は 1 よりも大きいため, 間違って前者の方が新しいバージョンとして扱われてしまいます).
このような場合には PORTEPOCH バージョンを 増やしてください. 上のセクション 0 で説明したように, PORTEPOCH がゼロでない場合には, それがパッケージ名の後ろにつけられます. PORTEPOCH は減らされたり, ゼロに リセットされることはありません. さもないと, 以前に作成された package との比較に失敗する (つまり, その package が古くなっていることがわからない) ためです: 新しいバージョン番号 (上の例では1.0,1) は 依然として前のバージョン番号 (20000801) よりも 数字としては小さいのですが, 自動化ツールが サフィックス ,1 を特別扱いすることで, 以前の package には明示されていないサフィックス ",0" よりも 新しいことがわかります.
大多数の ports では, PORTEPOCH が 必要になることは まず無いものと考えられています. また, 注意深く PORTVERSION を 使用することで, そのソフトウェアの将来のリリースが バージョン構造を変更する必要が出てきた場合にも, 多くの場合 前もって対応しておくことができるでしょう. しかし, 「スナップショット」リリースのように, オフィシャルな バージョン番号を持たないベンダーリリースが行なわれた時には, FreeBSD 版の port 作者によるケアが必要になります. そういったリリースに対し, リリース日付を使ったラベルを 付けたいという誘惑にかられることがあるでしょうが, そうすると新しい「オフィシャル」リリースが行なわれた時に, 上の例で示したような問題が起きることでしょう.
例えば, あるソフトウェアのスナップショットリリースが 20000917 に行なわれ, 以前のバージョン番号が 1.2 だったとすると, そのスナップショットの PORTVERSION には 20000917 ではなく 1.2.20000917 か何か, そのような番号を 指定するのが良いでしょう. そうしておけば, 例えばバージョン番号 1.3 として後続のリリースが 行なわれた場合にも, 大小関係が崩されずにすむわけです.
gtkmumble の port, バージョン 0.10 が ports collection にコミットされます.
PORTNAME= gtkmumble PORTVERSION= 0.10
PKGNAME は gtkmumble-0.10 になります.
ローカルな FreeBSD パッチを必要とする セキュリティホールが発見されました. それに合わせて PORTREVISION を増やします.
PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1
PKGNAME は gtkmumble-0.10_1 になります.
ベンダから 0.2 という番号が振られた 新バージョンがリリースされます (これにより, 作者は 0.10 という番号を ``0.9 の次という意味ではなく'', 実際には 0.1.0 のつもりで 使用していたことがわかります - あらら, 今さら遅すぎる). 新しいマイナーバージョン 2 は数字として 以前のバージョン番号 10 より小さいので, 強制的に新しい package の方を「より新しい」と認識させるため PORTEPOCH を増やす必要があります. これは新しいベンダーリリースなので, PORTREVISION は 0 にリセット (または Makefile から削除) されます.
PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1
PKGNAME は gtkmumble-0.2,1 になります.
次のリリースは 0.3 です. PORTEPOCH は減少することが無いため, 今度のバージョン変数は次のようになります:
PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1
PKGNAME は gtkmumble-0.3,1 になります.
Note: もし, このアップグレードによって PORTEPOCH が 0 に リセットされたとすると, 3 は数字として 10 よりも小さいため, gtkmumble-0.10_1 の package をインストールした誰かは gtkmumble-0.3 の package の方が新しいことに 気がつかないことになるでしょう.