Участие в документации Kubernetes

Edit This Page

Участие для опытных

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

Дежурный по PR на неделю

Утверждающие группы SIG Docs регулярно по очереди становятся дежурными по PR в репозитории и поэтому участвуют в графике ротации PR-дежурного на неделю.

В обязанности дежурного по PR входят:

  • Ежедневно проверять открытые пулреквесты для контроля качества и соблюдения рекомендаций по оформлению и содержимому.
    • В первую очередь просматривайте самые маленькие пулреквесты (size/XS), и только потом беритесь за самые большие (size/XXL).
    • Проверяйте столько пулреквестов, сколько сможете.
  • Проследить, что CLA подписан каждым участником.
    • Помогайте новым участникам подписать CLA.
    • Используйте этот скрипт, чтобы автоматически напомнить участникам, не подписавшим CLA, чтобы они подписали CLA.
  • Оставить свое мнение о предложенных изменениях и поспособствовать в проведении технического обзора от членов других SIG-групп.
    • Предложить исправления для измененного контента в PR.
    • Если вы хотите убедиться в правильности контента, прокомментируйте PR и задайте уточняющие вопросы.
    • Добавьте нужны метки с sig/.
    • Если нужно, то назначьте рецензентов из секции reviewers: в фронтальной части файла.
    • Добавьте метки Docs Review и Tech Review для установки статуса проверки PR.
    • Добавьте метку Needs Doc Review или Needs Tech Review для пулреквестов, которые ещё не были проверены.
    • Добавьте метку Doc Review: Open Issues или Tech Review: Open Issues для пулреквестов, которые были проверены и требуют дополнительную информацию и выполнение действия перед слиянием.
    • Добавьте метки /lgtm и /approve для пулреквестов, которые могут быть приняты.
  • Объедините пулреквесты, если они готовы, либо закройте те, которые не могут быть приняты.
  • Ежедневно отсортируйте и пометьте новые заявки. Обратитесь к странице Участие для опытных для получения информации по использование метаданных SIG Docs.

Полезные ссылки на GitHub для дежурных

Следующие ссылки помогут при дежурстве. После обработки заявок по трём первым ссылкам, как правило, список пулреквестов для проверки сократится. По указанным ссылкам вы найдете PR только в английскую версию, предназначенные для слияния в ветку master (кроме последней ссылки).

  • Нет CLA, нет права на слияние: напомните участнику подписать CLA. Если об этом уже напомнил и бот, и человек, то закройте PR и напишите автору, что он может открыть свой PR после подписания CLA. Не проверяйте PR, если их авторы не подписали CLA!
  • Требуется LGTM: если нужен проверка с технической точки зрения, попросите её провести одного из рецензентов, который предложил бот. Если требуется просмотр пулреквест со стороны группы документации или вычитка, то предложите изменения, либо сами измените PR, чтобы ускорить процесс принятия пулреквеста.
  • Имеет LGTM, нужно одобрение со стороны группы документации: выясните, нужно ли внести какие-либо дополнительные изменения или обновления, чтобы принять PR. Если по вашему мнению PR готов к слияния, оставьте комментарий с текстом /approve.
  • Быстрые результаты: если маленький PR направлен в основную ветку и не имеет условий для объединения. (поменяйте “XS” в метке с размером при работе с другими пулреквестами [XS, S, M, L, XL, XXL]).
  • Вне основной ветки: если PR отправлен в ветку dev-, значит он предназначается для будущего выпуска. Убедитесь, что release meister знает об этом, добавив комментарий с /assign @<meister's_github-username>. Если он направлен в старую ветку, помогите автору PR изменить на более подходящую ветку.

Когда закрывать пулреквесты

Обзоры и одобрения — это только один из способов, позволяющих держать список PR коротким и актуальным. Закрытие пулреквестов — альтернативный метод для этого.

  • Можете закрыть любой PR, если CLA-соглашение не было подписано в течение двух недель. Авторы PR могут повторно открыть PR после подписания CLA, так что это безопасный способ убедиться, что ничто не будет объединено без подписанного CLA.

  • Закройте любой PR, если автор не отреагировал на комментарии или проверки в течение 2 или более недель.

Не бойтесь закрывать пулреквесты. Участники с лёгкостью открыть и возобновить незаконченную работу. Зачастую уведомление о закрытии стимулировать автора возобновить и закончить свой вклад.

Чтобы закрыть пулреквест, оставьте комментарий /close в PR.

Заметка: Бот fejta-bot автоматически помечает заявки как устаревшие после 90 дней отсутствия активности, а затем закрывает их после ещё 30 дней простоя, когда они становятся тухлыми. Дежурные по PR должны закрывать заявки после 14-30 дней бездействия.

Внесение улучшений

Члены SIG Docs могут предлагать улучшения.

После того, как вы давно начали работать над документацией Kubernetes, у наверняка появились какие-нибудь идеи по улучшению руководства по оформлению, руководства по оформлению, набору инструментов, который используется для создания документации, стилизации сайта, процессов проверки и объединения пулреквестов. Для максимальной открытости подобные типы предложений по улучшению должны обсуждаться на встречи SIG Docs или в списке рассылки kubernetes-sig-docs. Помимо этого, это поможет разъяснить, как всё устроено в данный момент, и объяснить, почему так было принято, прежде чем предлагать радикальные изменения. Самый быстрый способ узнать ответы на вопросы о том, как в настоящее время работает документация, это задать их на канале #sig-docs Slack на kubernetes.slack.com.

Когда обсуждение состоялось, а SIG-группа согласилась с желаемым результатом, вы можете работать над предлагаемыми изменениями наиболее приемлемым способом. Например, обновление руководства по оформлению или функциональности сайта может включать открытие пулреквеста, а изменение, связанное с тестированием документации, может предполагать взаимодействие с sig-testing.

Координация документации по выпуску Kubernetes

Утверждающие SIG Docs могут координировать документацию для выпуска Kubernetes.

Каждый выпуск Kubernetes координируется командой людей, участвующих в специальной группе (Special Interest Group, SIG) sig-release. Другие члены команды в данном выпуске включают в себя общего руководителя выпуском, а также представителей sig-pm, sig-testing и др. Чтобы узнать больше о процессах выпуска версий Kubernetes, обратитесь к https://github.com/kubernetes/sig-release.

Представитель SIG Docs для данного выпуска координирует следующие задачи:

  • Мониторинг электронной таблицы с отслеживанием функциональности на наличие новых или измененных возможностей, затрагивают документацию. Если документация для определенной функциональности не будет готова к выпуску, возможно, она не попадет в выпуск.
  • Регулярное посещение встречи sig-release и обновлять информацию о статусе документации в выпуске.
  • Проверка и вычитка документации по функциональности, подготовленной SIG-группой, ответственной за реализацию этой функциональности.
  • Объединение связанных с выпуском пулреквестов и поддержка Git-ветки выпуска.
  • Консультируйте других участников SIG Docs, которые хотят научиться выполнять эту роль в будущем. Это называется сопровождение (shadowing).
  • Публикация изменений в документации, связанные с выпуском при размещении артефактов.

Координация выпуска обычно занимает 3-4 месяца, а обязанности распределяются между утверждающими SIG Docs.

Амбассадор нового участника

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

Амбассадоры новых участников работают бок о бок, чтобы поприветствовать новых участников SIG Docs, предлагать PR новым участникам и консультировать новых участников в их собственных PR.

Обязанности амбассадоров новых участников включают в себя:

  • Отвечать на вопросы новых участников на Slack-канале Kubernetes #sig-docs.
  • Совместно работать с дежурным по PR, чтобы определять заявки, которые подойдут для решения новыми участниками.
  • Консультировать новых участников в их PR.
  • Помогать новых участникам в создании более сложных PR, чтобы они могли стать членами Kubernetes.
  • Оказывать содействие участникам на их пути становления членом в Kubernetes.

Текущие амбассадоры новых участников объявляются на каждом собрании SIG Docs и на канале #sig-docs в Kubernetes.

Поддержка нового участника

Рецензенты SIG Docs могут содействовать новым участникам в членстве организации.

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

Новые участники документации могут найти спонсоров в канале #sig-docs в в Slack Kubernetes или в списке рассылки SIG Docs. Если вы осознали полезность работы автора заявки на членство, вы добровольно можете поддержать (спонсировать) его. Когда они подадут заявку на членство, отреагируйте на заявку “+1” и напишите подробный комментарий о том, почему вы считаете, что кандидат отлично вписывается в члены организации Kubernetes.

Сопредседатель SIG

Утверждающие SIG Docs могут быть сопредседателями SIG Docs.

Требования

Сопредседатели должны соответствовать следующим требованиям:

  • Быть утверждающим SIG Docs не меньше 6 месяцев
  • Руководить выпуском документации Kubernetes или сопровождать два выпуска
  • Понимание рабочих процессов и инструментов SIG Docs: git, Hugo, локализация, блог
  • Понимать, как другие SIG-группы и репозитории Kubernetes влияют на рабочий процесс SIG Docs, включая: команды в k/org, процессы в k/community, плагины в k/test-infra и роль SIG Architecture.
  • Уделять не менее 5 часов в неделю (но зачастую больше) в течение как минимум 6 месяцев для выполнения обязанностей.

Обязанности

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

Обязанности включают в себя:

  • Сосредоточить группу SIG Docs на достижении максимального счастья для разработчиков через отличную документацию
  • Быть примером соблюдения [норм поведения сообщества]https://github.com/cncf/foundation/blob/master/code-of-conduct.md) и контролировать их выполнение членами SIG
  • Изучение и внедрение передовых практик для SIG-группы, обновляя рекомендации по участию
  • Планирование и проведение встреч SIG: еженедельные обновления информации, ежеквартальные ретроспективные/плановые совещания и многое другое
  • Планирование и проведение спринтов по документации на мероприятиях KubeCon и других конференциях
  • Набирать персонал и выступать в поддержку CNCFCloud Native Computing Foundation и его платиновых партнеров, включая Google, Oracle, Azure, IBM и Huawei.
  • Поддерживать нормальную работу SIG

Проведение продуктивных встреч

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

Соблюдайте нормы поведения сообщества:

  • Привлекайте самый широкий круг участников к дискуссии и уважительно общайтесь между собой, стараясь никого не обидеть.

Сформулируйте четкую повестку дня:

  • Определите конкретную цель встречи
  • Опубликуйте программу дня заранее

Для еженедельных встреч скопируйте примечания из предыдущей недели в раздел “Past meetings”.

Работайте вместе для создания точных примечания:

  • Запишите обсуждение встречи
  • Подумайте над тем, чтобы делегировать роль стенографист кому-нибудь другому

Определяйте решения по пунктам повестки четко и точно:

  • Записывайте решения по пунктам, кто будет ими заниматься и ожидаемую дату завершения

Руководите обсуждением, когда это необходимо:

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

Уважайте время людей:

  • Начинайте и заканчивайте встречи своевременно

Используйте Zoom эффективно:

Исполнение роли ведущего в Zoom

Запись встреч на Zoom

Когда вам потребуется начать запись, нажмите пункт с надписью Record to Cloud.

Если нужно остановить запись, нажмите на кнопку Stop.

Запись автоматически загрузится на YouTube.

Обратная связь