Теги и состав выпуска

После согласования каталога требуется понимать, какая версия исходников относится к будущему выпуску. Название папки «последняя» недостаточно: оно не объясняет, что было включено и как вернуться к тому же снимку. Рассмотрим тег Git и отдельное описание состава выпуска.

Сценарий lesson-16 архива использует исправленный каталог предыдущего урока. Все действия здесь являются подготовленной моделью. Тег, сборка, архив исходников и публикация не создавались; настоящий репозиторий ProfessorWeb не изменяется.

Имя выбранного снимка

В начале лабораторный main содержит две правильные ссылки и абзац о порядке чтения. Рабочее дерево чистое. Мы выбираем эту конкретную запись как исходную точку учебного выпуска catalog-v0.1.0. Тег даёт ей удобное имя, которое сохраняется при дальнейшем движении ветки.

Создадим аннотированный тег в ручном сценарии:

git status --short
git tag -a catalog-v0.1.0 -m "Учебный каталог с порядком чтения"
git show catalog-v0.1.0

Ожидается объект тега с пояснением и ссылка на выбранный коммит. Документация tag описывает аннотированные теги. Здесь мы используем их для человеческого объяснения выбранной точки, а не как автоматическое доказательство качества содержимого.

Название отражает учебный пример, а не действительную версию ProfessorWeb. В реальном проекте команда заранее определяет схему имён и правила выпуска. Важно, чтобы одно имя не переиспользовалось для разных снимков после передачи коллегам. Иначе два человека будут обсуждать «одну версию», имея разные данные.

Теперь добавьте в README новую незавершённую идею и сохраните её отдельным коммитом. Ветка main перейдёт вперёд, но catalog-v0.1.0 по-прежнему обозначает предыдущую точку. Это полезное различие: ветка обычно сопровождает развитие, а тег обозначает выбранный снимок.

Исходники и результат сборки

Для нашего небольшого каталога можно прочитать файл прямо из тега:

git show catalog-v0.1.0:content/courses.md
git log --oneline --decorate -3

Ожидается согласованный список с двумя ссылками. Новый абзац README в последующей записи не входит в отмеченную версию. Это объясняет, почему описание выпуска нельзя автоматически составлять из текущих рабочих файлов: к моменту описания они могли уже измениться.

Тег сам по себе не создаёт HTML. Для статического сайта понадобятся выбранные исходники, генератор, зависимости и настройки. Затем появится сборочный артефакт — конкретный набор страниц и ресурсов. Даже если исходный коммит один и тот же, незакреплённые зависимости или разные настройки могут изменить результат.

Поэтому состав будущего выпуска лучше описывать отдельно. В сценарии подготовлен файл release/draft.md вне рабочего проекта. Он содержит имя тега, перечень ключевых исходников, ожидаемые URL и честный статус сборки. Идентификатор коммита остаётся заполнителем до действительной ручной подготовки истории.

release: catalog-v0.1.0
source_commit: REPLACE_WITH_ACTUAL_COMMIT_ID
source_paths:
  - content/courses.md
  - public/theme.css
expected_urls:
  - /courses/javascript/
  - /courses/html-css/
build_status: not_run
deployment_status: not_run

Это учебное описание, не подтверждение существующего артефакта. Поле состояния позволяет отличить выбранные исходники от готовых страниц. Если позже сборка выполнена, в описание можно добавить фактическое имя артефакта и его контрольную сумму. В текущем сценарии такой суммы нет: её нельзя придумывать по названию версии.

Область тега и область передачи

Созданный локально тег ещё не обязательно доступен коллегам. Передача ветки и передача конкретного тега являются отдельными намерениями. Для будущей согласованной отправки используется явное имя тега, но в нашем уроке настоящего сервера нет, и отправка не производится.

Не используйте широкий набор тегов автоматически, если требуется передать одну выбранную версию. В репозитории могут находиться личные учебные отметки и другие ещё не согласованные точки. Читателю полезнее увидеть точный объект и его назначение, чем получить необъяснимый набор исторических названий.

Аннотированная запись тоже не является криптографическим доказательством авторства. Подписание тега — отдельная возможность с собственными ключами и правилами проверки. Наше упражнение её не настраивает. Пояснение «учебный каталог» помогает понять назначение, но не подтверждает доверие к неизвестному источнику файла.

Также тег не хранит произвольное состояние окружения. Незаписанный черновик, локальная база, параметры панели хостинга и состояние кеша не попадают в отмеченный снимок исходников. Для выбранного набора нужно заранее решить, какие данные являются исходными и какие описываются как условия сборки или эксплуатации.

Полезно заранее решить, какое имя получит результат сборки, когда он появится. Оно может содержать имя версии и фактический идентификатор источника, но название само по себе не подтверждает совпадение файлов. Контрольная сумма относится к конкретному артефакту, а тег — к выбранному источнику; это разные доказательства. В нашем документе нет ни сборочного архива, ни рассчитанной суммы, поэтому оба поля не выдаются за известные данные. Если после выбора тега изменилось описание курса, новая редакция должна получить новую исходную точку, а не незаметную замену содержимого прежнего имени. Иначе поздний читатель не сможет восстановить, что именно обсуждалось. Такой договор особенно полезен для серии учебных материалов: ссылки могут оставаться одинаковыми, а содержание закономерно развиваться. Версия объясняет состояние текста и шаблонов в определённый момент, сохраняя постоянный адрес страницы для посетителя.

Возврат к определённому результату

Представьте, что будущий выпуск показывает неправильный каталог. Чтобы обсуждать возврат, сначала сопоставьте опубликованный артефакт с его источником. Если известен только тег, но отсутствует готовый прежний артефакт, потребуется отдельная сборка старого снимка в воспроизводимом окружении. Перемещение Git-указателя само по себе не меняет хостинг.

Для ProfessorWeb такой договор особенно полезен при сохранении старых URL. В описание выпуска входят не только новые красивые страницы, но и набор прежних путей, которые должны продолжать отвечать. Тег связывает решение с исходниками, а перечень артефактов и наблюдений связывает их с фактически доступным сайтом.

В учебном сценарии конечное состояние содержит тег на согласованном снимке и следующий коммит README на main. Их разные позиции видны на схеме. Рабочие файлы ожидаемо отражают последний main; просмотр через тег отражает прежнюю выбранную версию. Никаких утверждений об опубликованном результате из этого не следует.

Подготовленное описание можно передать коллеге для обсуждения состава, даже пока сборка не разрешена. Оно явно отделяет известные исходники от невыполненных действий. В следующем уроке откроем две рабочие папки одной истории, чтобы сравнение версии и новая задача не мешали друг другу.