Перейти к содержанию

Коммит в документацию

Документация Stormbpmn находится в репозитории https://github.com/KotskinKotskin/stormbpmn_new_doc и открыта для коммитмента всем желающим. Чтобы процесс создания и правки материалов был простым — мы написали эту статью, в которой расскажем, как правильно подойти к работе с репозиторием и документацией по шагам.

Сначала расскажем о том, как устроена документация, чтобы вам было проще ориентироваться в ней.

Устройство документации

В корневой директории документации находятся следующие файлы:

  • toc.yaml — оглавление документации. После добавления новых страниц материалов их необходимо внести в оглавление. Пути указываются от корня документации. Если в названии материала присутствует двоеточие — применяются одинарные кавычки.
  • vars.yaml — переменные документации для текущей локали.
  • global_vars.yaml — общие переменные для всех локалий.
  • index.md — домашняя страница документации.

Структура документации:

.
├── _templates # Шаблоны уведомлений
├── admins     # Материалы для администраторов команд
├── all        # Материалы для всех
├── analytics  # Материалы для аналитиков
├── approvals  # Материалы для ревьюнеров и согласующих
├── architects # Материалы для системных архитекторов
├── beginners  # Материалы для начинающих
├── main       # Материалы для разделов FAQ, быстрый старт, видеозаписи, о документации 
├── mock       # Техническая секция документации

Статьи размещены в поддиректориях и имеют определенную структуру:

  • index.md — текст статьи в формате .md. Применение HTML-разметки не запрещено.
  • .meta.yml — метаданные статьи для SEO и некоторых систем сборок на базе JS.
  • /img — поддиректория с изображениями/иллюстрациями.

В файле .meta.yml обязательно должен быть прописан title:, он используется в качестве H1 в index.md — Коммит в документацию.

Правка материалов

Если вы заметили какую-то неточность или ошибку в документации — ее можно поправить прямо в репозитории с помощью встроенного инструмента — (карандаш для редактирования файлов). Нажмите на , внесите правку в документ и нажмите на кнопку Commit changes:

git_commit_changes

В открывшемся окне Propose changes:

  1. Заполните поле Commit message: укажите кратко, какие изменения были внесены.
  2. По желанию заполните Extended description: опишите более детально, какие правки были внесены.
  3. Переключите чекбокс выбора способа коммитмента на Create a new branch for this commit and start a pull request.
  4. Название новой ветви должно отражать суть внесенных изменений. Например: patch, fix, edit.
  5. Нажмите кнопку Propose changes.

git_propose_changes

После нажатия на кнопку Propose changes откроется окно подготовки PR (Pull Request):

  • Поле Add a title будет автоматически заполнено с предыдущего шага.
  • Текстовый блок Add a description также будет заполнен автоматически, если до этого было заполнено поле Extended description.
  • Кнопка Create pull request создаст новую ветвь и запрос на внесение изменений в основную ветвь репозитория.

git_pr_prepare

Теперь необходимо протестировать, что внесенные изменения применились правильно, а документация собирается без ошибок. Для этого в поле Add a comment введите: /mkdocs build dev и нажмите кнопку Comment. Через несколько секунд появится emoji 👀 — это значит, что сборка документации стартовала. Если сборка документации не удалась — в комментариях появится отчет с ошибками, если вы не понимаете, что пошло не так — не тратьте на это время, а оставьте комментарий и призовите ревьюера (как это сделать, описано ниже).

Если сборка прошла успешно — в комментарии появится ссылка на собранную документацию:

build_ready

После проверки сборки документации нужно призвать ревьюера в PR, так как без его согласия и ревью применить правки нельзя — ветка main защищена от бесконтрольного вливания изменений. Для призыва ревьюера нажмите на пункт Reviewers справа вверху от первого комментария и выберите из списка любого ревьюера:

reviewer_call

Ревьюер будет оповещен и проверит PR. После этого PR вольют в основной репозиторий.

Добавление новых материалов

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

Инструкция копирования репозитория на локальную машину:

  1. Кликните по кнопке Fork и выберите пункт Create a new fork из выпадающего списка:

    git_fork_repo

    Будет сделан fork репозитория в ваше GitHub-пространство.

  2. Кликните по зеленой кнопке <> Code и в появившемся меню нажмите на кнопку копировать справа от поля с URL репозитория:

    git_clone

  3. Перейдите в терминал своей ОС или IDE, перейдите в директорию, в которую хотите скопировать репозиторий, и введите команду: git clone <Ctr+v>. Будет создана одноименная с репозиторием директория, где будет находиться содержимое репозитория.

Последовательность создания статьи:

  1. Перейдите в клонированный репозиторий, создайте новую ветку, в которой будете вести разработку материала: git checkout -b <branch_name>. Старайтесь называть ветви осознанно и интуитивно понятно, например, если вы пишете для аналитиков, то название ветви может быть таким: analytics/add_process.
  2. Выполните команду git branch, чтобы убедиться, что вы находитесь в нужной вам ветке. Текущая ветка будет помечена звездочкой.
  3. Создайте поддиректорию в нужной вам части документации (см. «Устройство документации» выше), создайте index.md и .meta.yml. Заполните index.md и укажите новую статью в toc.yaml.

  4. Сохраните изменения в git последовательностью команд:

  5. git add -A — добавить все отслеживаемые файлы, которые были изменены в коммит.

  6. git commit -m "что было сделано" — добавить все изменения в PR.
  7. git push origin — отправить ветку в удаленный репозиторий и создать PR.

Перейдите в репозиторий https://github.com/KotskinKotskin/stormbpmn_new_doc, нажмите на кнопку Pull requests в верхней панели инструментов и кликните по своему PR в списке пул-реквестов:

git_choose_pr

Откроется окно подготовки PR (Pull Request):

  • Поле Add a title будет автоматически заполнено.
  • Текстовый блок Add a description должен содержать список выполненных работ по документации.
  • Кнопка Create pull request создаст запрос на внесение изменений в основную ветвь репозитория.

git_pr_prepare

Теперь необходимо протестировать, что внесенные изменения применились правильно, а документация собирается без ошибок. Для этого в поле Add a comment введите: /mkdocs build dev и нажмите кнопку Comment. Через несколько секунд появится emoji 👀 — это значит, что сборка документации стартовала. Если сборка документации не удалась — в комментариях появится отчет с ошибками, если вы не понимаете, что пошло не так — не тратьте на это время, а оставьте комментарий и призовите ревьюера (как это сделать, описано ниже).

Если сборка прошла успешно — в комментарии появится ссылка на собранную документацию:

build_ready

После проверки сборки документации нужно призвать ревьюера в PR, так как без его согласия и ревью применить правки нельзя — ветка main защищена от бесконтрольного вливания изменений. Для призыва ревьюера нажмите на пункт Reviewers справа вверху от первого комментария и выберите из списка любого ревьюера:

reviewer_call

Ревьюер будет оповещен и проверит PR. После этого PR вольют в основной репозиторий.