Управление версиями и автоматизация

Последнее обновление: 22 сент. 2026 г. / Официальная архитектурная спецификация EpoCanvas

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

1. Правила семантических номеров версий (SemVer)

Номер версии имеет формат vмажорная.минорная.патч-версия (сейчас v1.3.1):

Тип изменения	Пример	Когда срабатывает
Основная версия (Major)	`v2.0.0`	Крупный рефакторинг документационной системы (например, обновление основной версии Astro, полная замена макета).
Минорная версия (Minor)	`v1.2.0`	Заметные новые функции: новые разделы документации, добавление новых языков, обновление дизайн-системы и т.п.
Патч-версия (Patch)	`v1.2.1`	Мелкие изменения: исправление опечаток, обновление примеров кода, корректировка мелких стилей.

2. Стандартный процесс выпуска новой версии из 3 шагов

Шаг 1: описать обновления (`RELEASE_NOTES.md`)

Опишите в RELEASE_NOTES.md в корне проекта, что именно обновилось; содержимое этого файла станет текстом описания GitHub Release:

## [v1.2.1] - 2026-09-14

### Исправления
- Исправлена опечатка в команде в разделе о развёртывании.
- Скриншоты интерфейса обновлены до последней версии.

Шаг 2: обновить номер версии в package.json

Бейдж версии в панели навигации автоматически связан с полем version в package.json, которое служит единственным источником данных о версии для всего сайта (Single Source of Truth). Обновите номер версии в package.json (или выполните pnpm version patch) — бейдж в верхней панели автоматически синхронизируется с новым номером, вручную менять его в нескольких местах не нужно:

{
  "name": "epocanvas-docs",
  "version": "1.2.1"
}

Шаг 3: зафиксировать код и поставить Git-тег

# 1. Зафиксировать все изменения
git add .
git commit -m "chore(release): bump version to v1.2.1"
git push origin main

# 2. Поставить соответствующий тег версии и отправить его
git tag v1.2.1
git push origin v1.2.1

3. Автоматический конвейер публикации на GitHub Actions

В проекте заранее настроен автоматический рабочий процесс публикации в .github/workflows/release.yml; его фактическое содержимое:

name: Release

on:
  push:
    tags:
      - 'v*'   # автоматически срабатывает при отправке тегов, начинающихся с v

permissions:
  contents: write

jobs:
  release:
    name: Publish GitHub Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          TAG_NAME="${{ github.ref_name }}"
          echo "Publishing release for tag: ${TAG_NAME}"
          # 同名 release 已存在时（例如重新推送 tag，或 tag 删除后旧 release 转为草稿）先删掉，再按当前 RELEASE_NOTES.md 重新发布
          gh release delete "${TAG_NAME}" --yes 2>/dev/null || true
          gh release create "${TAG_NAME}" \
            --title "EpoCanvas Docs ${TAG_NAME}" \
            --notes-file RELEASE_NOTES.md \
            --latest

После отправки тега v1.2.1 GitHub автоматически запустит конвейер:

извлекает код репозитория;
используя RELEASE_NOTES.md в качестве описания, создаёт официальный релиз на странице Releases репозитория и помечает его как latest;
кликнув бейдж версии в верхней панели, читатели могут просмотреть архив всех прошлых версий.

4. Процесс совместной работы над контентом

Когда документацию ведут несколько человек, работа строится по фиксированной схеме «ветка → проверка → слияние → публикация», чтобы содержимое сайта всегда собиралось:

Ветка main (всегда готова к публикации, соответствует сайту на продакшене)
  │
  ├─ 1. От ветки main создаётся функциональная ветка   git checkout -b docs/new-guide
  ├─ 2. Написание/правка Markdown
  ├─ 3. Локальная самопроверка                          pnpm exec astro check && pnpm run build
  ├─ 4. Отправка ветки и открытие Pull Request          запускает сборку CI
  ├─ 5. После одобрения проверкой слияние в main        запускает автоматическое развёртывание на сайте
  └─ 6. При необходимости выпустить версию ставится тег v*   запускает конвейер GitHub Release

На что обращать внимание при проверке Pull Request

CI (build.yml) гарантирует только то, что «сборка проходит»; следующие вопросы проверяются человеком:

Работоспособность ссылок: ведут ли куда-то новые внутренние ссылки и якоря; зарегистрировано ли перенаправление для документов со сменившимся путём;
Результат рендеринга: корректно ли отображаются на странице синтаксис ::: в выносках и аннотации блоков кода (CI визуальную часть не проверяет);
Соответствие текста и изображений: снабжены ли новые скриншоты подписями и достаточно ли они чёткие;
Правила именования: имена файлов в нижнем регистре с дефисами, заполненные title и description во Frontmatter.

Роль	Обязанности
Автор документации	Пишет контент, проверяет локально, инициирует PR
Проверяющий	Сверяет результат рендеринга и ссылки, сливает код
Администратор выпуска	Ставит теги версий, ведёт `RELEASE_NOTES.md`, синхронизирует бейдж версии в панели навигации

5. Проверка сборки в CI

В репозитории настроен .github/workflows/build.yml: при каждом пуше в ветку main и в каждом Pull Request автоматически выполняются установка зависимостей и полная сборка, что заранее выявляет проблемы этапа сборки — битые ссылки, ошибки Frontmatter и т.д. Прогоните ту же проверку локально перед коммитом, чтобы CI не падал после пуша:

pnpm exec astro check && pnpm run build