diff --git a/content/ru/docs/contribute/participating.md b/content/ru/docs/contribute/participating.md new file mode 100644 index 0000000000..2460e19d6d --- /dev/null +++ b/content/ru/docs/contribute/participating.md @@ -0,0 +1,208 @@ +--- +title: Участие в SIG Docs +content_template: templates/concept +card: + name: contribute + weight: 40 +--- + +{{% capture overview %}} + +SIG Docs — это одна из [специальных групп](https://github.com/kubernetes/community/blob/master/sig-list.md) в проекте Kubernetes, которая занимается написанием, обновлением и поддержкой документации Kubernetes в целом. Перейдите на страницу про [SIG Docs в GitHub-репозитории](https://github.com/kubernetes/community/tree/master/sig-docs), чтобы узнать подробную информацию об этой группе. + +SIG Docs активно принимает правки и дополнения в документацию, так и отзывы от всех участников. Любой может открыть пулреквест (PR), либо сообщить про ошибки в тексте или просто прокомментировать выполняемые пулреквесты. + +Вы также можете стать [членом](#члены), [рецензентом](#рецензенты) или [утверждающим](#утверждающие). Эти роли расширяют ваши возможности, но и предлагают выполнение определенных обязанностей по рассмотрению и принятию изменений. Изучите содержимого файла [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) в директории сообщества репозитория, чтобы узнать про членство в сообществе Kubernetes. В остальной части этой страницы кратко рассматривается функционирование ролей в группе SIG Docs, которая в совокупности отвечает за поддержание одного из самой публичной части Kubernetes — сайта и документации Kubernetes. + +{{% /capture %}} + +{{% capture body %}} + +## Роли и обязанности + +- **Любой** может поучаствовать в документацию Kubernetes. Для этого вам нужно только [подписать CLA](/docs/contribute/start#sign-the-cla) и иметь аккаунт на GitHub. +- **Члены** организации Kubernetes — участники, которые активно занимаются пректом Kubernetes, как правило, открывая пулреквесты с принятыми изменениями. Посмотрите файл [Членство в сообществе](https://github.com/kubernetes/community/blob/master/community-membership.md), чтобы узнать про необходимые условия для членства. +- **Рецензент** SIG Docs — член организации Kubernetes, который занимается проверкой пулреквестов и поэтому был добавлен в соответствующую группу на GitHub и в файлы `OWNERS` в GitHub-репозитории. +- **Утверждающий** SIG Docs — член организации с хорошей репутацией, который подтвердил неизменную приверженность проекту. Утверждающий может принимать пулреквесты и публиковаться от имени организации Kubernetes. Утверждающие также могут представлять группу SIG Docs в более крупном сообществе Kubernetes. Некоторые из задач утверждающего SIG Docs, например, координация новой версии, требуют значительных затрат по времени. + +## Любой + +Кто угодно может сделать следующее: + +- Открыть ишью на GitHub в любую часть Kubernetes, включая документацию. +- Дать рекомендацию или предложить улучшение в пулреквесте. +- Предложить идею по улучшению в Slack](http://slack.k8s.io/) или в [список рассылки SIG Docs](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). +- Использовать команду `/lgtm` (сокращение от "looks good to me") бота Prow, чтобы одобрить изменения в пулреквесте. + {{< note >}} + Если вы не входите в организацию Kubernetes, то команда `/lgtm` не проставил автоматически соответствующую метку. + {{< /note >}} + +После [подписания CLA](/docs/contribute/start#sign-the-cla) каждый также может: +- Открыть пулреквест, чтобы улучшить существующий текст, либо что-то новое, или написать запись в блоге или описать пример использования. + +## Члены + +Члены — это участники проекта Kubernetes, которые удовлетворяют [критериям членства](https://github.com/kubernetes/community/blob/master/community-membership.md#member). SIG Docs ценит участие всех членов сообщества Kubernetes и часто просит дать обратную связь от членов других SIG-групп для соблюдения технической точности. + +Любой член [организации Kubernetes](https://github.com/kubernetes) может сделать следующее: + +- Всё то же самое, что и [любой другой участник](#любой) +- Использовать команду `/lgtm` в комментарии для автоматического добавления метки LGTM (looks good to me) для пулреквеста. +- Использовать команду `/hold` в комментарии для блокировки слияния пулреквеста, если он имеет метку LGTM и другие утверждающие метки. +- Использовать команду `/assign` в комментарии, чтобы назначить рецензента, который будет проверят пулреквест. + +### Членство + +После того, как вы успешно отправили не менее 5 содержательных пулреквестов, вы можете стать [членом](https://github.com/kubernetes/community/blob/master/community-membership.md#member) организации Kubernetes. Следуйте нижеперечисленным шагам: + +1. Найдите двух рецензентов или утверждающих, которые [поддержат](/docs/contribute/advanced#sponsor-a-new-contributor) ваше членство. + + Запросите спонсорство в канале [#sig-docs Kubernetes Slack](https://kubernetes.slack.com) или в [списке рассылки SIG Docs](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). + + {{< note >}} + Не отправляйте электронное письмо и не пишите личное сообщение в Slack кому-либо из участников SIG Docs. + {{< /note >}} + +2. Создайте ишью в репозитории `kubernetes/org`, чтобы запросить членство. + Заполните шаблон, предварительно изучив правила [членства в сообществе](https://github.com/kubernetes/community/blob/master/community-membership.md). + +3. Сообщите вашим спонсорам про вашу заявку на GitHub, упомянув их в ней на GitHub (добавив комментарий в форме `@`), либо отправив им ссылку напрямую, чтобы они могли добавить проголосовать ( `+1`). + +4. Когда ваше членство будет одобрено, член административной команды на GitHub, назначенный для обработки вашего пулреквеста, обновит ишью на GitHub, чтобы показать одобрение, а затем закроет проблему GitHub. + Поздравляем, теперь вы член организации! + +Если ваша заявка на членство не была одобрена, членский комитет даст уточнения или перечислит шаги, которые необходимо выполнить, прежде чем снова подать заявку. + +## Рецензенты + +Рецензенты — это члены GitHub-группы [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews). Рецензенты проверяют пулреквесты документации и оставлять обратную связь по предлагаемым изменениях. Рецензенты могут: + +- Делать всё то, что и [любой участник](#любой) и [члены](#члены) +- Писать документацию для новой функциональности +- Назначать метки и классифицировать ишью +- Проверять пулреквесты и оставлять обязательные для выполнения рекомендации +- Создавайте диаграммы, графику и встраиваемые скринкасты и видеоролики +- Заниматься локализацией +- Редактировать строки в коде, относящиеся к интерфейсу пользователя +- Улучшать комментарии к коду + +### Выбор рецензентов для проверки пулреквестов + +Процесс выбора рецензентов для проверки пулреквестов автоматизирован. Вы можете попросить проверку у определенного рецензента, написав комментарий в пулреквесте: `/assign [@_github_handle]`. Чтобы показать, что пулреквест является правильным с технической точки зрения и не требует дополнительных изменений, рецензент добавляет комментарий с командой `/lgtm`. + +Если назначенный рецензент еще не просмотрел содержимое пулреквеста, может присоединиться другой проверяющий. Кроме того, вы можете назначить технических рецензентов и подождать их одобрение через комментарий с `/lgtm`. + +Также для совсем небольшого изменения, или такого, которое не требует технического рассмотрения, [утверждающие](#утверждающие) SIG Docs одобрить его через комментарий с `/lgtm`. + +Комментарий с `/approve` от рецензента игнорируется ботом и поэтому соответствующая метка не добавится к пулреквесту. + +### Как стать рецензентом + +Если вы соответствуете [требованием](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), то можете стать рецензентом SIG Docs. Рецензенты в других SIG-группах должны подать новую заявку для получения статуса рецензента в SIG Docs. + +Для отправки заявки откройте пулреквест с добавлением самого себя в секцию `reviewers` [корневого файла OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) в репозитории `kubernetes/website`. Запросите проверку вашего пулреквеста одному или нескольким текущим утверждающим в группе SIG Docs. + +Если ваш пулреквест одобрен, вы становитесь рецензентом SIG Docs. Теперь бот [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) будет назначать и предлагать вас в качестве рецензента для проверки новых пулреквестов. + +После того, как ваша кандидатура будет одобрена, попросите текущего утверждающего SIG Docs добавить вас в GitHub-группу [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews). Только члены GitHub-группы `kubernetes-website-admins` могут добавлять новых членов в какую-либо другую группу. + +## Утверждающие + +Утверждающие — члены GitHub-группы [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers). Перейдите в раздел [Команды и группы в SIG Docs](#teams-and-groups-within-sig-docs) для получения дополнительной информации. + +Утверждающие могут делать следующее: + +- Все то же, что и [обычные участники](#любой), [члены](#члены) и [рецензенты](#рецензенты) +- Публиковать изменения от других участников путём одобрения и слияния пулреквестов с помощью комментария с командой `/approve`. + Если кто-то оставляет комментарий, не являясь при этом официальным рецензентом, бот проигнорирует такой одобряющий комментарий. +- Примите участие в работе команды выпуска новых версий Kubernetes как представитель документации +- Предлагать улучшения в руководстве по оформлению +- Предлагать улучшения для тестов документации +- Предлагать улучшения для сайта Kubernetes или других инструментов + +Если у PR есть метка `/lgtm`, или если утверждающий оставляет комментарий с командной с `/lgtm`, PR автоматически сливается. Утверждающий SIG Docs должен оставлять комментарий с `/lgtm` только для тех изменений, которые не нуждаются в дополнительном техническом обзоре. + +### Как стать утверждающим + +Если вы соответствуете [требованием](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), вы можете стать утверждающим SIG Docs. Утверждающие в других SIG-группах должны подать новую заявку для получения статуса утверждающего в SIG Docs. + +Для отправки заявки откройте пулреквест с добавлением самого себя в секцию `approvers` [корневого файла OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) в репозитории `kubernetes/website`. Запросите проверку вашего пулреквеста одному или нескольким текущим утверждающим в группе SIG Docs. + +Если ваш пулреквест одобрен, вы становитесь утверждающим SIG Docs. Теперь бот [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) будет назначать и предлагать вас в качестве рецензента для проверки новых пулреквестов. + +После того, как ваша кандидатура будет одобрена, попросите текущего утверждающего SIG Docs добавить вас в GitHub-группу[@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers). Только члены GitHub-группы `kubernetes-website-admins` могут добавлять новых членов в какую-либо другую группу. + +### Обязанности утверждающего + +Утверждающие улучшают документацию, проверяя и сливая пулреквесты в репозитории сайта. Из-за того, эта роль предусматривает дополнительные привилегии, на утверждающих возлагаются дополнительные обязанности: + +- Утверждающие могут использовать команду `/approve`, которая сливает PR в репозиторий. + + Невнимательное слияние может нарушить работу сайта, поэтому имейте это в виду, когда объединяете какой-либо пулреквест. + +- Убедитесь, что предлагаемые изменения соответствуют [правилам по содержанию](/docs/contribute/style/content-guide/#contributing-content). + + Если вы сомневаетесь или вы не уверены в чем-либо, не стесняйтесь обращаться для дополнительной проверки. + +- Проверьте, что тесты на Netlify пройдены успешно, перед тем как написать комментарий с `/approve` в PR. + + Netlify tests must pass before approving + +- Перед одобрением пулреквеста перейдите на предварительный просмотр сайта на Netlify для сделанных изменений в PR, и убедитесь, что всё содержимое выглядит хорошо. + +- Участвуйте в [графике дежурства смотрителя PR](https://github.com/kubernetes/website/wiki/PR-Wranglers), чтобы вас назначили дежурным проверяющим на неделю. SIG Docs ожидает, что все утверждающие примут участие в этом графике. За подробностям обратитесь к странице [Be the PR Wrangler for a week](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week). + +## Председатель SIG Docs + +Каждая SIG-группа, включая SIG Docs, выбирает одного или нескольких членов из своей SIG-группы в качестве председателей. Это координаторы между SIG Docs и другими подразделениями в организации Kubernetes. От таких людей требуются обширные знания о структуре проекта Kubernetes в целом и как функционирует группа SIG Docs внутри неё. Смотрите раздел [Руководство](https://github.com/kubernetes/community/tree/master/sig-docs#leadership), чтобы узнать текущий список председателей. + +## Команды SIG Docs и автоматизация + +Автоматизация в SIG Docs основывается на двух разных механизмах: +группы GitHub и файлы OWNERS. + +### GitHub-группы + +Группа SIG Docs представлена двумя командами на GitHub: + + - [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers) + - [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews) + +На каждую из них можно сослаться по имени (`@name`) в комментариях на GitHub, чтобы общаться со всеми участниками в этой группе. + +Эти команды пересекаются, но назначение у них разное. Для назначения людей на ишью, пулреквестов и поддержки одобрений в PR бот использует информацию из файлов OWNERS. + +### Файлы OWNERS и вступительная часть + +Проект Kubernetes использует инструмент автоматизации под названием prow, чтобы автоматизировать процесс, связанный с ишью и пулреквестами на GitHub. [Репозиторий сайта Kubernetes](https://github.com/kubernetes/website) использует два [плагина prow](https://github.com/kubernetes/test-infra/tree/master/prow/plugins): + +- blunderbuss +- approve + +Все эти плагины используют файлы [OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) и [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES) в корневой директории GitHub-репозитория `kubernetes/website`, чтобы контролировать работу prow по всему репозиторию. + +Файл OWNERS содержит список людей, которые являются рецензентами и утверждающими в SIG Docs. Файлы OWNERS также может быть в поддиректориях и могут переопределять тех, кто может выступать в качестве рецензента или утверждающего в изменениях файлов этой директории и её поддиректорий. Для получения дополнительной информации о файлах OWNERS в целом, перейдите в [OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md). + +Кроме того, в каждом Markdown-файле могут быть указаны рецензенты и утверждающие в так называемой вступительной части (front-matter) в виде логинов участников или имён групп на GitHub. + +Таким образом файлы OWNERS и вступительная часть в Markdown-файлах определяет своего рода рекомендацию для бота, чтобы он знал, к кому обращаться за технической и редакционной проверкой каждого PR. + +## Как происходит слияние + +Когда пулреквест сливается в действующую ветку сайта (в данный момент это `master`), содержимое публикуется и становится общедоступным. Для обеспечения высокого качества публикуемого нами контента, мы доверяем слияние пулреквестов утверждающим SIG Docs. Ниже описан этот процесс. + +- Когда пулреквест имеет метки `lgtm` и `approve`, при этом у него нет метки `hold`, и то же время все тесты успешно проходят, то пулреквест автоматически сливается. +- Члены организации Kubernetes и утверждающие SIG Docs могут оставлять комментарии со специальными командами, которые блокирует автоматическое объединение пулреквеста (добавление комментарий с текстом `/hold` или удаление ранее установленной метки `/lgtm`). +- Любой участник Kubernetes может добавить метку `lgtm`, добавив комментарий, включающий в себя `/lgtm`. +- Только утверждающие SIG Docs могут слить пулреквест путём добавления комментария с `/approve`. Некоторые утверждающие также играют дополнительные роли, например, [смотрителя PR](#pr-wrangler) или [председателя SIG Docs](#председатель-sig-docs). + +{{% /capture %}} + +{{% capture whatsnext %}} + +Для получения дополнительной информации про участие в документации Kubernetes, посмотрите следующие страницы: + +- [Начало участия](/ru/docs/contribute/start/) +- [Правила оформления документации](/ru/docs/contribute/style/) + +{{% /capture %}}