5.2 Именование

5.2.2.1 PORTREVISION

Переменная PORTREVISION представляет собой монотонно увеличивающееся число, которое обнуляется при каждом увеличении значения переменной PORTVERSION (то есть каждый раз, когда создателями выпускается новый официальный релиз), и добавляется к имени пакаджа, если оно не равно нулю. Изменения в PORTREVISION используются автоматизированными инструментами (например, pkg_version(1)) для определения факта появления нового пакаджа.

Значение PORTREVISION должно увеличиваться каждый раз, когда в порте FreeBSD делаются изменения, которые достаточно сильно затрагивают содержимое или структуру соответствующего пакаджа.

Примеры случаев, когда значение PORTREVISION должно быть увеличено:

• Добавление патчей для исправления пробелов в безопасности, ошибок, или добавления новой функциональности в порт.

• Изменения в файле Makefile порта для включения и выключения параметров, определяемых при компиляции пакаджа.

• Изменения в списке упаковки или в поведении пакаджа во время его установки (например, изменение скрипта, генерирующего начальные данные для пакаджа, такие, как ssh-ключи для хоста).

• Увеличение версии динамической библиотеки, от которой зависит порт (в этом случае тот, кто попытается установить старый пакадж после установки более новой версии библиотеки, не сможет этого сделать, потому что при этом будет делаться поиск старой библиотеки libfoo.x, а не libfoo.(x+1)).

• Большие функциональные изменения в дистрибутивном файле порта, происходящие без объявлений, и приводящие к большим изменениям, то есть изменения в дистрибутиве требуют корректировки файла distinfo без соответствующего изменения PORTVERSION, когда как команда diff -ru между новой и старой версиями показывает нетривиальные изменения в коде.

Примеры изменений, которые не требуют увеличения переменной PORTREVISION:

• Изменения стиля в скелете порта без функциональных изменений в пакадже.

• Изменения в переменной MASTER_SITES или другие функциональные изменения порта, которые не затрагивают получающегося пакаджа.

• Тривиальные патчи к дистрибутивному файлу, такие, как исправления опечаток, которые не так уж важны, что пользователи пакаджа должны озаботиться обновлением.

• Исправления, касающиеся этапа построения, которые делают возможным построение пакаджа, если ранее это было невозможно сделать (пока изменения не приводят к изменению работы на любых других платформах, на которых порт ранее строился). Так как PORTREVISION отражает содержимое пакаджа, то, если ранее пакадж не строился, то нет нужды увеличивать PORTREVISION для отметки изменения.

Правило, которому нужно приблизительно следовать, заключается в том, что нужно спрашивать себя, является ли вносимое в порт изменение таким, что от него выиграют все (в виде усовершенствования, исправления или благодаря тому, что новый пакадж будет вообще работоспособным), и примите во внимание тот факт, что при этом все, кто регулярно обновляют своё дерево портов, будут обязаны это сделать. Если это так, то переменная PORTREVISION должна быть увеличена.

5.2.2.2 PORTEPOCH

Время от времени разработчик программного обеспечения или создатель порта FreeBSD делают что-то не так и выпускают версию программы, номер которой меньше предыдущей версии. Примером этого является порт, название которого меняется с foo-20000801 на foo-1.0 (изначально это не считалось бы более новой версией, так как 20000801 численно больше, чем 1).

В ситуациях, подобных этой, должно быть увеличено значение PORTEPOCH. Если значение PORTEPOCH не равно нулю, то оно добавляется к имени пакаджа, как описано в разделе выше. Значение PORTEPOCH никогда не должно уменьшаться или сбрасываться в ноль, потому что это приведёт к ошибке сравнения с пакаджем с меньшим номером эпохи (то есть то, что пакадж устарел, обнаружено не будет): номер новой версии (например, 1.0,1 в примере выше) останется меньше, чем номер предыдущей версии (20000801), однако суффикс ,1 интерпретируется различными автоматизированными утилитами особым образом, и окажется больше, чем предполагаемый суффикс ,0 более раннего пакаджа).

Некорректное уменьшение или сброс PORTEPOCH приводит к печальным последствиям; если вы не поняли, о чём шла речь ранее, пожалуйста, всё же разберитесь с этим, либо спросите в списках рассылки.

Предполагается, что в большинстве портов переменная PORTEPOCH использоваться не будет, но при корректном использовании PORTVERSION может появиться необходимость её иметь, если в будущих релизах программное обеспечение должно изменить структуру номера версии. Однако создателям портов нужно быть внимательными, когда разработчик выпускает релиз без официального номера версии -- эдакие ``промежуточные'' релизы. Имеется соблазн пометить релиз датой его выхода, что может вызвать проблемы, как и в примере выше, когда будет выпущен новый ``официальный'' релиз.

Например, если промежуточный релиз помечен датой 20000917, а предыдущая версия программного обеспечения имела номер 1.2, то промежуточному релизу должно быть поставлено в соответствие значение PORTVERSION, равное 1.2.20000917 или что-то похожее, но не 20000917, так как последующий релиз, скажем, 1.3, должен иметь численно большее значение.

5.2.2.3 Пример использования переменных PORTREVISION и PORTEPOCH

Выполнен коммит порта gtkmumble, версии 0.10, в коллекцию портов.

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.1.0, а не ``то, что будет выпущено после версии 0.9'' - извините, теперь уже поздно). Так как новый младший номер версии 2 по значению меньше, чем номер предыдущей версии 10, то должно быть увеличено значение PORTEPOCH для того, чтобы заставить распознавать вновь создаваемый пакадж как ``более новый''. Так как это новый релиз программы, то PORTREVISION обнуляется (или удаляется из файла 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