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

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

Роли

• Автор — человек, предлагающий изменения в документации.
• Основной ревьюер — человек, тщательно проверяющий предложенные изменения согласно контрольному списку.
• Финальный ревьюер — человек, повторно проверяющий изменения с использованием того же контрольного списка и утверждающий 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-запросу, а автор их учитывает. Ожидаемое время ответа для каждой итерации ревью составляет два рабочих дня, до нескольких недель в случае форс-мажора.

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

   • Включает auto-merge для pull-запроса.
   • Отклоняет свой устаревший отзыв c комментарием «lgtm».
   • Передаёт процесс финальному ревьюеру для дополнительной проверки свежим взглядом.

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

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

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

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

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

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

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

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

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

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

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

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

См. также

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