Участие в SIG Docs

SIG Docs — это одна из специальных групп в проекте Kubernetes, которая занимается написанием, обновлением и поддержкой документации Kubernetes в целом. Перейдите на страницу про SIG Docs в -репозитории, чтобы узнать подробную информацию об этой группе.

SIG Docs активно принимает правки и дополнения в документацию, так и отзывы от всех участников. Любой может открыть пулреквест (PR), либо сообщить про ошибки в тексте или просто прокомментировать выполняемые пулреквесты.

Вы также можете стать членом, рецензентом или утверждающим. Эти роли расширяют ваши возможности, но и предлагают выполнение определенных обязанностей по рассмотрению и принятию изменений. Изучите содержимого файла community-membership в директории сообщества репозитория, чтобы узнать про членство в сообществе Kubernetes. В остальной части этой страницы кратко рассматривается функционирование ролей в группе SIG Docs, которая в совокупности отвечает за поддержание одного из самой публичной части Kubernetes — сайта и документации Kubernetes.

Роли и обязанности

• Любой может поучаствовать в документацию Kubernetes. Для этого вам нужно только подписать CLA и иметь аккаунт на .
• Члены организации Kubernetes — участники, которые активно занимаются пректом Kubernetes, как правило, открывая пулреквесты с принятыми изменениями. Посмотрите файл Членство в сообществе, чтобы узнать про необходимые условия для членства.
• Рецензент SIG Docs — член организации Kubernetes, который занимается проверкой пулреквестов и поэтому был добавлен в соответствующую группу на и в файлы OWNERS в -репозитории.
• Утверждающий SIG Docs — член организации с хорошей репутацией, который подтвердил неизменную приверженность проекту. Утверждающий может принимать пулреквесты и публиковаться от имени организации Kubernetes. Утверждающие также могут представлять группу SIG Docs в более крупном сообществе Kubernetes. Некоторые из задач утверждающего SIG Docs, например, координация новой версии, требуют значительных затрат по времени.

Любой

Кто угодно может сделать следующее:

• Открыть ишью на в любую часть Kubernetes, включая документацию.
• Дать рекомендацию или предложить улучшение в пулреквесте.
• Предложить идею по улучшению в Slack](http://slack.k8s.io/) или в список рассылки SIG Docs.
• Использовать команду /lgtm (сокращение от "looks good to me") бота Prow, чтобы одобрить изменения в пулреквесте.

  Примечание:

  Если вы не входите в организацию Kubernetes, то команда /lgtm не проставил автоматически соответствующую метку.

После подписания CLA каждый также может:

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

Члены

Члены — это участники проекта Kubernetes, которые удовлетворяют критериям членства. SIG Docs ценит участие всех членов сообщества Kubernetes и часто просит дать обратную связь от членов других SIG-групп для соблюдения технической точности.

Любой член организации Kubernetes может сделать следующее:

• Всё то же самое, что и любой другой участник
• Использовать команду /lgtm в комментарии для автоматического добавления метки LGTM (looks good to me) для пулреквеста.
• Использовать команду /hold в комментарии для блокировки слияния пулреквеста, если он имеет метку LGTM и другие утверждающие метки.
• Использовать команду /assign в комментарии, чтобы назначить рецензента, который будет проверят пулреквест.

Членство

После того, как вы успешно отправили не менее 5 содержательных пулреквестов, вы можете стать членом организации Kubernetes. Следуйте нижеперечисленным шагам:

1. Найдите двух рецензентов или утверждающих, которые поддержат ваше членство.

   Запросите спонсорство в канале #sig-docs Kubernetes Slack или в списке рассылки SIG Docs.

   Примечание:

   Не отправляйте электронное письмо и не пишите личное сообщение в Slack кому-либо из участников SIG Docs.
   

2. Создайте ишью в репозитории kubernetes/org, чтобы запросить членство. Заполните шаблон, предварительно изучив правила членства в сообществе.

3. Сообщите вашим спонсорам про вашу заявку на , упомянув их в ней на (добавив комментарий в форме @<-username>), либо отправив им ссылку напрямую, чтобы они могли добавить проголосовать ( +1).

4. Когда ваше членство будет одобрено, член административной команды на , назначенный для обработки вашего пулреквеста, обновит ишью на , чтобы показать одобрение, а затем закроет проблему . Поздравляем, теперь вы член организации!

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

Рецензенты

Рецензенты — это члены -группы @kubernetes/sig-docs-pr-reviews. Рецензенты проверяют пулреквесты документации и оставлять обратную связь по предлагаемым изменениях. Рецензенты могут:

• Делать всё то, что и любой участник и члены
• Писать документацию для новой функциональности
• Назначать метки и классифицировать ишью
• Проверять пулреквесты и оставлять обязательные для выполнения рекомендации
• Создавайте диаграммы, графику и встраиваемые скринкасты и видеоролики
• Заниматься локализацией
• Редактировать строки в коде, относящиеся к интерфейсу пользователя
• Улучшать комментарии к коду

Выбор рецензентов для проверки пулреквестов

Процесс выбора рецензентов для проверки пулреквестов автоматизирован. Вы можете попросить проверку у определенного рецензента, написав комментарий в пулреквесте: /assign [@__handle]. Чтобы показать, что пулреквест является правильным с технической точки зрения и не требует дополнительных изменений, рецензент добавляет комментарий с командой /lgtm.

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

Также для совсем небольшого изменения, или такого, которое не требует технического рассмотрения, утверждающие SIG Docs одобрить его через комментарий с /lgtm.

Комментарий с /approve от рецензента игнорируется ботом и поэтому соответствующая метка не добавится к пулреквесту.

Как стать рецензентом

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

Для отправки заявки откройте пулреквест с добавлением самого себя в секцию reviewers корневого файла OWNERS в репозитории kubernetes/website. Запросите проверку вашего пулреквеста одному или нескольким текущим утверждающим в группе SIG Docs.

Если ваш пулреквест одобрен, вы становитесь рецензентом SIG Docs. Теперь бот K8s-ci-robot будет назначать и предлагать вас в качестве рецензента для проверки новых пулреквестов.

После того, как ваша кандидатура будет одобрена, попросите текущего утверждающего SIG Docs добавить вас в -группу @kubernetes/sig-docs-pr-reviews. Только члены -группы kubernetes-website-admins могут добавлять новых членов в какую-либо другую группу.

Утверждающие

Утверждающие — члены -группы @kubernetes/sig-docs-maintainers. Перейдите в раздел Команды и группы в SIG Docs для получения дополнительной информации.

Утверждающие могут делать следующее:

• Все то же, что и обычные участники, члены и рецензенты
• Публиковать изменения от других участников путём одобрения и слияния пулреквестов с помощью комментария с командой /approve. Если кто-то оставляет комментарий, не являясь при этом официальным рецензентом, бот проигнорирует такой одобряющий комментарий.
• Примите участие в работе команды выпуска новых версий Kubernetes как представитель документации
• Предлагать улучшения в руководстве по оформлению
• Предлагать улучшения для тестов документации
• Предлагать улучшения для сайта Kubernetes или других инструментов

Если у PR есть метка /lgtm, или если утверждающий оставляет комментарий с командной с /lgtm, PR автоматически сливается. Утверждающий SIG Docs должен оставлять комментарий с /lgtm только для тех изменений, которые не нуждаются в дополнительном техническом обзоре.

Как стать утверждающим

Если вы соответствуете требованием, вы можете стать утверждающим SIG Docs. Утверждающие в других SIG-группах должны подать новую заявку для получения статуса утверждающего в SIG Docs.

Для отправки заявки откройте пулреквест с добавлением самого себя в секцию approvers корневого файла OWNERS в репозитории kubernetes/website. Запросите проверку вашего пулреквеста одному или нескольким текущим утверждающим в группе SIG Docs.

Если ваш пулреквест одобрен, вы становитесь утверждающим SIG Docs. Теперь бот K8s-ci-robot будет назначать и предлагать вас в качестве рецензента для проверки новых пулреквестов.

После того, как ваша кандидатура будет одобрена, попросите текущего утверждающего SIG Docs добавить вас в -группу@kubernetes/sig-docs-maintainers. Только члены -группы kubernetes-website-admins могут добавлять новых членов в какую-либо другую группу.

Обязанности утверждающего

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

• Утверждающие могут использовать команду /approve, которая сливает PR в репозиторий.

  Невнимательное слияние может нарушить работу сайта, поэтому имейте это в виду, когда объединяете какой-либо пулреквест.

• Убедитесь, что предлагаемые изменения соответствуют правилам по содержанию.

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

• Проверьте, что тесты на Netlify пройдены успешно, перед тем как написать комментарий с /approve в PR.

  

• Перед одобрением пулреквеста перейдите на предварительный просмотр сайта на Netlify для сделанных изменений в PR, и убедитесь, что всё содержимое выглядит хорошо.

• Участвуйте в графике дежурства смотрителя PR, чтобы вас назначили дежурным проверяющим на неделю. SIG Docs ожидает, что все утверждающие примут участие в этом графике. За подробностям обратитесь к странице Be the PR Wrangler for a week.

Председатель SIG Docs

Каждая SIG-группа, включая SIG Docs, выбирает одного или нескольких членов из своей SIG-группы в качестве председателей. Это координаторы между SIG Docs и другими подразделениями в организации Kubernetes. От таких людей требуются обширные знания о структуре проекта Kubernetes в целом и как функционирует группа SIG Docs внутри неё. Смотрите раздел Руководство, чтобы узнать текущий список председателей.

Команды SIG Docs и автоматизация

Автоматизация в SIG Docs основывается на двух разных механизмах: группы и файлы OWNERS.

-группы

Группа SIG Docs представлена двумя командами на :

• @kubernetes/sig-docs-maintainers
• @kubernetes/sig-docs-pr-reviews

На каждую из них можно сослаться по имени (@name) в комментариях на , чтобы общаться со всеми участниками в этой группе.

Эти команды пересекаются, но назначение у них разное. Для назначения людей на ишью, пулреквестов и поддержки одобрений в PR бот использует информацию из файлов OWNERS.

Файлы OWNERS и вступительная часть

Проект Kubernetes использует инструмент автоматизации под названием prow, чтобы автоматизировать процесс, связанный с ишью и пулреквестами на . Репозиторий сайта Kubernetes использует два плагина prow:

• blunderbuss
• approve

Все эти плагины используют файлы OWNERS и OWNERS_ALIASES в корневой директории -репозитория kubernetes/website, чтобы контролировать работу prow по всему репозиторию.

Файл OWNERS содержит список людей, которые являются рецензентами и утверждающими в SIG Docs. Файлы OWNERS также может быть в поддиректориях и могут переопределять тех, кто может выступать в качестве рецензента или утверждающего в изменениях файлов этой директории и её поддиректорий. Для получения дополнительной информации о файлах OWNERS в целом, перейдите в OWNERS.

Кроме того, в каждом Markdown-файле могут быть указаны рецензенты и утверждающие в так называемой вступительной части (front-matter) в виде логинов участников или имён групп на .

Таким образом файлы OWNERS и вступительная часть в Markdown-файлах определяет своего рода рекомендацию для бота, чтобы он знал, к кому обращаться за технической и редакционной проверкой каждого PR.

Как происходит слияние

Когда пулреквест сливается в действующую ветку сайта (в данный момент это master), содержимое публикуется и становится общедоступным. Для обеспечения высокого качества публикуемого нами контента, мы доверяем слияние пулреквестов утверждающим SIG Docs. Ниже описан этот процесс.

• Когда пулреквест имеет метки lgtm и approve, при этом у него нет метки hold, и то же время все тесты успешно проходят, то пулреквест автоматически сливается.
• Члены организации Kubernetes и утверждающие SIG Docs могут оставлять комментарии со специальными командами, которые блокирует автоматическое объединение пулреквеста (добавление комментарий с текстом /hold или удаление ранее установленной метки /lgtm).
• Любой участник Kubernetes может добавить метку lgtm, добавив комментарий, включающий в себя /lgtm.
• Только утверждающие SIG Docs могут слить пулреквест путём добавления комментария с /approve. Некоторые утверждающие также играют дополнительные роли, например, дежурного по PR или председателя SIG Docs.

Что дальше

Для получения дополнительной информации про участие в документации Kubernetes, посмотрите следующие страницы:

• Участие для начинающих
• Правила оформления документации