210 lines
26 KiB
Markdown
210 lines
26 KiB
Markdown
---
|
||
title: Участие в SIG Docs
|
||
content_type: concept
|
||
card:
|
||
name: contribute
|
||
weight: 40
|
||
---
|
||
|
||
<!-- 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.
|
||
|
||
|
||
|
||
<!-- body -->
|
||
|
||
## Роли и обязанности
|
||
|
||
- **Любой** может поучаствовать в документацию Kubernetes. Для этого вам нужно только [подписать CLA](/ru/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](/ru/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. Найдите двух рецензентов или утверждающих, которые [поддержат](/ru/docs/contribute/advanced#поддержка-нового-участника) ваше членство.
|
||
|
||
Запросите спонсорство в канале [#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 (добавив комментарий в форме `@<GitHub-username>`), либо отправив им ссылку напрямую, чтобы они могли добавить проголосовать ( `+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.
|
||
|
||
<img src="/images/docs/contribute/netlify-pass.png" width="75%" alt="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](/ru/docs/contribute/advanced#дежурный-по-pr-на-неделю).
|
||
|
||
## Председатель 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).
|
||
|
||
|
||
|
||
## {{% heading "whatsnext" %}}
|
||
|
||
|
||
Для получения дополнительной информации про участие в документации Kubernetes, посмотрите следующие страницы:
|
||
|
||
- [Участие для начинающих](/ru/docs/contribute/start/)
|
||
- [Правила оформления документации](/ru/docs/contribute/style/)
|
||
|
||
|