Управление версиями

Adaptadocx координирует публикации документации на разных языках с помощью семантического версионирования, метаданных компонентов Antora и CI-workflow, основанных на Git-тегах.

Семантическое версионирование

Строка версии: MAJOR.MINOR.PATCH

Сегмент Пояснение

MAJOR

Несовместимые изменения

MINOR

Новые функции без ломки

PATCH

Исправления ошибок / только docs
Хронология примеров
1.0.0  → первый релиз
1.1.0  → новые возможности
1.1.1  → фиксы / docs
2.0.0  → несовместимое изменение

Правила Git

Тег и публикация
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin --tags
Table 1. Типы веток
Ветка Назначение Шаблон

main

Стабильный код

main

Feature

Новая функциональность

feature/*

Release

Подготовка релиза (редко)

release/vX.Y.Z

Hot-fix

Срочный патч

hotfix/vX.Y.Z

Версии компонентов Antora

У каждой локали свой antora.yml. Для сборок по тегам Antora подставляет версию из Git-тега. Для сборок по веткам контент публикуется под псевдоверсией current (или именем ветки). Плейсхолдеры в репозитории не требуются.

Английский
name: adaptadocx
version: 'current'   # сборка по тегам переопределит автоматически
title: Adaptadocx Documentation
Русский
name: adaptadocx
version: 'current'   # сборка по тегам переопределит автоматически
title: Документация Adaptadocx

Логика определения версии

Используется fallback-стратегия, чтобы и релизы по тегам, и сборки по веткам разрешались корректно.

Структура каталогов
build/asm/
├── <locale>/
│   ├── 1.2.0/      ← релиз по тегу v1.2.0
│   └── current/    ← сборка по ветке без тега
Порядок

  1. Ищем …/<version>/.

  2. Если нет, используем …/current/.

CI и объём сборки

  • Локальные / PR-сборки — по умолчанию BUILD_SCOPE=local, собирается только текущая ветка (BUILD_REF=HEAD).

  • Релизные сборки — BUILD_SCOPE=tags, Antora строит все версии по Git-тегам.

Пример (release workflow)
- name: Build docs in container
  run: |
    docker run --rm -v "${{ github.workspace }}:/work" adaptadocx:latest \
      bash -lc 'npm ci --no-audit --prefer-offline && make clean && make build-all BUILD_SCOPE=tags'

Размещение артефактов

Версионирование кодируется каталогами, имена файлов стабильные.

Формат Путь вывода

PDF (EN)

build/pdf/en/<version>/adaptadocx-en.pdf → копируется в site/en/<version>/_downloads/adaptadocx-en.pdf

PDF (RU)

build/pdf/ru/<version>/adaptadocx-ru.pdf → копируется в site/ru/<version>/_downloads/adaptadocx-ru.pdf

DOCX (EN)

build/docx/en/<version>/adaptadocx-en.docx → копируется в site/en/<version>/_downloads/adaptadocx-en.docx

DOCX (RU)

build/docx/ru/<version>/adaptadocx-ru.docx → копируется в site/ru/<version>/_downloads/adaptadocx-ru.docx

Ссылки в шапке UI указывают на _downloads текущей версии, например:

  • '_downloads/adaptadocx-en.pdf'

  • '_downloads/adaptadocx-en.docx'

  • '_downloads/adaptadocx-ru.pdf'

  • '_downloads/adaptadocx-ru.docx'

Чек-лист релиза

  1. Обновите version в package.json при необходимости.

  2. При изменении ветки или start_path — проверьте playbook’и.

  3. Соберите обе локали, проверьте индекс поиска.

  4. Поставьте тег и запушьте (vX.Y.Z).

  5. Убедитесь, что артефакты EN и RU лежат в site/<locale>/<version>/_downloads/ и build/(pdf|docx)/<locale>/<version>/.

См. также