This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Инструкция по совместной работе над документацией в парадигме Docs-as-Code с использованием упрощённого GitHub Flow

Настоящая инструкция описывает рабочий процесс для двух участников (Катя и Максим), использующих Git и Forgejo. Подход основан на упрощённом GitHub Flow: одна защищённая основная ветка (main) и краткосрочные ветки задач ([new|fix|upd]/*).

Полезная информация: Pro Git.

1. Начальная настройка

1.1. Защита main-ветки [✅]

1. Перейдите в репозиторий на Forgejo.
2. Откройте Settings → Branches.
3. В разделе Protected Branches нажмите Add Protected Branch.
4. В поле Branch name укажите main.
5. Включите опции:
   • Protect pushes to this branch
   • Include administrators
   • Require pull request approvals before merging → установите Approvals required = 1.

Эти настройки для репозитория SandBox выполнены. Прямой git push в ветку main запрещён. Все изменения должны поступать только через Pull Request с одобрением второго участника.

2. Именование веток

main — основная ветка (полностью проработанная и утвержденная документация, готовая к публикации в любой момент времени);

Каждая задача выполняется в отдельной feature-ветке. Название должно быть понятным и отражать суть задачи. Используемые префиксы:

• new/ — создание новой документации (добавление новых страниц, разделов);
• edit/ — редактирование (плановое) существующей документации (развитие документа, наполнение его содержанием и т.д.);
• fix/ — исправление существенных логических или смысловых ошибок в документации (не корректура и не обновление);
• upd/ — обновления, связанные с развитием документации (не меняется логика или смысл).

Другие префиксы могут создаваться по необходимости.

Примеры:

• new/task-0123 — создание глоссария
• fix/task-0123 — исправление описания пользователя;
• upd/task-0123 — обновление описания пользователя.

Общий формат: тип/task-0000. (Всегда 4 знака, ведущие нули — по необходимости).

3. Ежедневный рабочий цикл

3.1. Перед началом работы

Обновите локальную копию основной ветки.

git checkout main
git pull origin main

3.2. Создание ветки задачи

Создайте новую ветку от актуального main.

git checkout -b new/task-0000

3.3. Внесение изменений и коммиты

1. Отредактируйте файлы документации.

2. Добавьте изменения в индекс:

git add .

(или выберите конкретные файлы: `git add path/to/file.md`)

3. Сделайте коммит с понятным сообщением:

git commit -m "Исправление опечатки во введении"

Рекомендации по коммит-сообщениям:

• Заголовок —
  • не более 50 символов (желательно);
  • не более 72 символов (строго);
  • первая буква — заглавная;
  • ⚠️ в конце заголовка точка не ставится!
• Заголовок от тела (если оно есть) должен быть отделен пустой строкой. Если тело представлено, то в конце тела ставится точка.

• Первое слово — краткое страдательное причастие прошедшего времени в форме, согласованной с объектом (в единственном или множественном числе): например, «Создан...», «Исправлен...», «Устранены...» и так далее.
• Сообщение должно быть кратким, но информативным. Оно не должно содержать общих фраз.
• Хорошие примеры:
  • Создана новая страница;
  • Исправлены ошибки в описании Пользователя;
  • Добавлены новые сущности в Глоссарий;
  • Устранены несоответствия в описании событий, отправляемых Календарём;
  • Исправлены «битых ссылок» и т.д.

То есть, в целом, сообщение (комментарий) к коммиту должен быть прямым продолжением фразы

«Благодаря принятию этого коммита в проекте... »

Повторяйте шаги 2–3 по мере работы. Коммиты следует делать часто: по одной логической единице изменений.

3.4. Отправка изменений и создание Pull Request

Когда задача завершена:

1. Отправьте ветку на Forgejo:

git push origin fix/task-0000

2. Перейдите на страницу репозитория в Forgejo.
3. Нажмите кнопку Create Pull Request (появится автоматически после git push).
4. В форме PR:
   • Убедитесь, что base = main, а compare = ваша ветка.
   • Напишите краткое описание задачи (что было сделано, зачем).
   • Упомяните второго участника с помощью @имя, чтобы он получил уведомление.

3.5. Рецензирование Pull Request

Второй участник (рецензент):

• Переходит по ссылке на PR.
• Просматривает изменения во вкладке Files changed.
• Оставляет комментарии к конкретным строкам, если есть замечания.
• После проверки нажимает Approve.

Рекомендации по комментариям в PR:

• Будьте конкретны: укажите, какую именно строку или абзац нужно изменить.
• Предлагайте улучшения вежливо и конструктивно.
• Используйте разметку Markdown, если нужно (например, для выделения кода: `example`).

3.6. Внесение правок после рецензирования

Если рецензент просит внести правки:

1. Внесите изменения в ту же ветку локально.
2. Сделайте новый коммит:

git add .
git commit -m "Исправление формулировки по замечанию Кати"

3. Отправьте обновления:

git push origin fix/task-0000

PR автоматически обновится.

3.7. Слияние и очистка

После получения одобрения:

1. Автор PR нажимает Merge pull request.
2. Выбирает опцию Create a merge commit.
3. После слияния нажимает Delete branch (удалить ветку на сервере).
4. Локально удалите ветку:

git checkout main
git branch -d fix/task-0000

4. Дополнительные правила

4.1. Синхронизация во время работы

Если задача выполняется больше одного дня, периодически обновляйте свою ветку из main:

git checkout main
git pull origin main
git checkout ***/task-0000
git merge main

Если возникнут конфликты — разрешите их вручную, затем сделайте коммит.

4.2. Использование тегов в PR

В названии Pull Request можно использовать теги для быстрой классификации:

• ...
• ...

TBD (пока не понятно, какие теги ставить и зачем: подумаем, и применим по необходимости).

4.3. Связь с задачами (issues)

Если задача заведена как Issue в Forgejo и текущий PR её полностью закрывает:

• В описании PR укажите Closes #12 (где 12 — номер Issue).
• После слияния Issue автоматически закроется.