Процесс ревью документации YDB

Развивая общий обзор из Участие в разработке документации YDB, эта статья подробнее рассматривает, что происходит на этапе ревью pull-запроса с документацией.

Роли

• Автор — человек, предлагающий изменения в документации.
• Основной ревьюер — человек, тщательно проверяющий предложенные изменения согласно контрольному списку.
• Финальный ревьюер — человек, повторно проверяющий изменения с использованием того же контрольного списка и утверждающий pull-запрос на GitHub.

Процесс

1. Автор открывает pull-запрос на GitHub с предложенными изменениями в папке ydb/docs. Следование руководству по стилю с самого начала делает процесс ревью более гладким.

2. Автор обеспечивает, чтобы pull-запрос был в состоянии, готовом к ревью, соответствуя всем следующим критериям:

   1. Pull-запрос имеет * Documentation как единственную категорию в changelog. Если всё сделано правильно, автоматизация пометит pull-запрос меткой «documentation».
   2. Pull-запрос не помечен как черновик.
   3. Предложенные изменения успешно собираются, и автоматизация оставила комментарий со ссылкой на предпросмотр (вместо ошибок). Предпросмотр показывает изменённый контент как ожидается.

3. (опционально) Автор делится ссылкой на pull-запрос в чате сообщества или чате, связанном с документацией, для привлечения дополнительного внимания к нему.

4. Основной ревьюер назначается автоматически или выбирает pull-запрос из входящего списка с помощью кнопки «assign yourself» в правом сайдбаре, а затем предоставляет начальную обратную связь и набор предложений по улучшению.

   Временное исключение себя из автоматического назначения, если вы являетесь основным ревьюером

   

5. Автор и основной ревьюер совместно итеративно работают, пока предложенные изменения не пройдут контрольный список. Основной ревьюер предоставляет отзывы через комментарии к pull-запросу, а автор их учитывает. Ожидаемое время ответа для каждой итерации ревью составляет два рабочих дня, до нескольких недель в случае форс-мажора. Также основной ревьюер периодически пересматривает назначенные на себя pull-запросы и уточняет с авторами статус, если несколько рабочих дней в них ничего не происходит (в комментариях на GitHub, плюс по возможности в личной переписке).

6. Как только основной ревьюер подтверждает, что pull-запрос соответствует требованиям контрольного списка, он:

   • Включает auto-merge для pull-запроса. Если целевая ветка pull-запроса отличается от main, функция auto-merge будет недоступна: в этом случае основной ревьюер должен вручную нажать кнопку «Squash and merge» после одобрения финальным ревьюером на этапе 7.

• Отклоняет свой устаревший отзыв c комментарием «lgtm».

• Основной ревьюер передаёт процесс финальному ревьюеру для дополнительной проверки свежим взглядом. Как правило, это происходит личным сообщением, но т.к. весь этап 6 делается одновременно — по самому pull-запросу это событие всё равно видно по предыдущим подпунктам (включенному auto-merged и/или отклонённому отзыву основного ревьюера).

7. В зависимости от вердикта финального ревьюера:

   • Если финальный ревьюер нажимает кнопку Approve, pull-запрос начинает соответствовать одному из обязательных условий для мёрджа. Таким образом, если сборка всё ещё проходит, auto-merge GitHub, вероятно, автоматически вмёрджит pull-запрос. В противном случае любые проблемы должны быть устранены вручную.
   • Если финальный ревьюер предоставляет дополнительную обратную связь или предложения, процесс возвращается к шагу 5.

8. Если auto-merge не был включен на этапе 6, основной ревьюер нажимает кнопку «Squash and merge».

9. После попадания контента в ветку main, он будет автоматически опубликован на официальный сайт YDB посредством CI/CD.

10. Документация YDB многоязычная, и от авторов ожидается предоставление синхронизированных изменений для всех поддерживаемых языков (в настоящее время английский и русский), если это применимо. Если автор не знает все необходимые языки, допустимо использование LLM или машинного перевода. На каком этапе делать перевод зависит от сложности:

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

Контрольный список

Если PR добавляет новый контент в ветку main

• [ ] Текст понятен целевой аудитории статьи.
• [ ] Текст технически точен.
• [ ] Текст грамматически правильный, без пунктуационных, орфографических или типографских ошибок.
• [ ] Терминология консистентна. Первое упоминание каждого термина, используемого в статье, является ссылкой на его объяснение в Глоссарий YDB или известном доверенном источнике, таком как Википедия.
• [ ] Каждая новая статья правильно размещена в структуре документации.
• [ ] Каждая статья следует одному жанру и соответствует своему месту в структуре документации.
• [ ] Каждая новая статья включает ссылки на все релевантные существующие страницы документации, либо по ходу текста, либо в конце в разделе «См. также».
• [ ] Релевантные существующие статьи обновлены ссылками на новые статьи.
• [ ] Все новые статьи перечислены в YAML файлах с оглавлением и index.md их папки.
• [ ] Все переименованные или перемещённые статьи отражены в redirects.yaml.
• [ ] Тон повествования и стиль статьи соответствуют остальной документации или, как минимум, остаются консистентными внутри статьи.

Если PR является обратным переносом в стабильную ветку

Содержимое документации публикуется на сайте из нескольких Git-веток независимо. Аналогично разработке исходного кода, ветка main содержит документацию для будущих релизов, а документация для каждого конкретного выпуска YDB публикуется из стабильной ветки. Например, версии YDB v25.1 соответствует ветка stable-25-1. Если необходимо перенести документацию из ветки main в стабильную ветку через cherry-pick, создаётся отдельный PR с целевой веткой stable-***. Процесс проверки таких PR отличается, так как содержимое уже прошло ревью при слиянии в ветку main. В таком случае используйте следующий чек-лист:

• [ ] В PR для обратного переноса указаны идентификаторы или ссылки на один или несколько PR, в которых данный контент был добавлен в ветку main.
• [ ] Содержимое PR для обратного переноса совпадает с оригинальными PR в ветку main. Если структура документации была изменена, содержимое перенесено корректно.
• [ ] PR корректно собирается, предварительный просмотр формируется без ошибок и предупреждений, контент отображается в правильных местах.
• [ ] Отсутствуют артефакты слияния, такие как дублирующийся контент, Git-маркеры типа >>>>>>>> и другие аналогичные проблемы.
• [ ] Функциональность, описанная в документации, доступна в соответствующем релизе YDB. В случае сомнений уточните у автора или ответственного за эту функциональность.

Чем не является ревью документации

Тестирование

Ревью документации не является заменой тестирования. Если документация включает инструкции, автор несёт ответственность за обеспечение их правильности, реализацию автоматизированных тестов для поддержания точности со временем и т.д.

Основной ревьюер и/или финальный ревьюер могут проверить корректность описанных шагов в инструкции. Но это не является обязательной частью их роли.

Ревью технического дизайна

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

См. также

• Документация GitHub
• Документация Git