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

Kubernetes v1.17 документация больше не поддерживается. Версия, которую вы сейчас просматриваете, является статической. Актуальную документацию вы можете найти последняя версия.

Edit This Page

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

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

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

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

  • Концепции Kubernetes
  • Рабочие процессы документации Kubernetes
  • Поиск нужной информации о будущих возможностях Kubernetes
  • Сильные аналитические навыки в целом

Эти задачи не такие последовательные, как задачи для начинающих. Поэтому мы не ожидаем, что кто-то в одиночку будет постоянно заниматься всеми ими.

Знакомство с Prow

Prow — это система CI/CD, использующая Kubernetes, которая выполняет задания с пулреквестами (PR). Prow с помощью команд, похожих на те, что есть в чатботах, даёт возможность обрабатывать действия в организации Kubernetes на GitHub. Вы можете выполнять целый ряд действий, такие как добавление и удаление меток, закрытие заявок и назначение утверждающего. Введите Prow-команду в поле для комментария в формате /<command-name>. Некоторые популярные команды:

  • /lgtm (looks good to me): добавляет метку lgtm, которая сообщает, что рецензент проверил PR
  • /approve: одобряет PR так, чтобы он мог быть принят (эта команда работает только для утверждающих)
  • /assign: назначает проверяющего на PR
  • /close: закрывает ишью или PR
  • /hold: добавляет метку do-not-merge/hold, которая означает, что PR не может быть автоматически принят
  • /hold cancel: удаляет метку do-not-merge/hold
Заметка: Не все команды работают для каждого пользователя. Бот Prow сообщит вам, если вы пытаетесь выполнить команду, не разрешенную для вашего уровня.

Детально изучите список команд Prow, прежде чем начать проверять PR или сортировать ишью.

Проверка пулреквестов

Каждую неделю утверждающий доброволец документации сортирует и просматривает пулреквесты и заявки. Такой человек называется “PR Wrangler” на неделю. Расписание ведется с помощью планировщика PR Wrangler. Чтобы поучаствовать в этом списке, посетите еженедельную встречу SIG Docs. Даже если вас не выбрали дежурным по PR на текущую неделю, вы все равно можете проверять пулреквесты (PR), которые еще не были детально просмотрены.

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

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

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

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

Поиск пулреквестов для проверки

Чтобы посмотреть все открытые пулреквесты, перейдите на вкладку Pull Requests в GitHub-репозитории. PR можно проверять только, если он соответствует всем перечисленным ниже критериям:

  • Имеет метку cncf-cla:yes
  • Не содержит надписи WIP в описании
  • Не имеет тег с фразой do-not-merge
  • Нет конфликтов для слияния
  • Сделан в правильную ветку (обычно это master, за исключением, если PR не относится к невыпущенной ещё функциональности)
  • Не проверялся ещё детально другим проверяющим документации (то же самое касается и остальных технических рецензентов), если только этот человек явно не обратился за вашей помощью. В частности, не рекомендуется добавлять много новых комментариев после других циклов рассмотрения PR.

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

Если вы новичок в проверке пулреквестов или у вас недостаточно времени и возможностей, попробуйте поискать PR с тегом size/XS или size/S. Размер пулреквеста автоматически определяется по количеству изменённых строк в PR.

Рецензенты и утверждающие

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

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

    Заметка: Не добавляйте /lgtm, если вы не уверены в технической точности документации, измененной или добавленной в PR.

  • Утверждающий проверяет содержание запроса на предмет качества и соответствия рекомендациям SIG Docs, приведенным в руководствах по содержанию и оформлению. Только люди, указанные в качестве утверждающих в файле OWNERS, могут одобрить PR. Чтобы одобрить PR, оставьте комментарий /approve к PR.

PR объединяется, когда у него есть комментарий /lgtm от кого-либо из организации Kubernetes и комментарий /approve от утверждающего в группе sig-docs-maintainers, если он не удерживается, а автор PR подписал CLA.

Заметка: Раздел “Участие” содержит больше информации для рецензентов и утверждающих, включая конкретные обязанности для утверждающих.

Проверка PR

  1. Изучите описание PR вместе с указанными ишью и ссылками, если они есть. Кратковременные мимолетные обзоры иногда могут наносит больше вреда, чем пользы, поэтому убедитесь, что вы обладаете нужными знаниями, чтобы сделать содержательный обзор.

  2. Если кто-то другой может лучше всего проверит определенный PR, упомяните этого человека, добавив комментарий /assign @<github-username>. Если вы обратились за технической проверкой к человеку, который не занимается документацией, но при этом вы хотите сами посмотреть PR как участник группы документации, то не стесняйтесь это делать.

  3. Перейдите на вкладку Files changed. Посмотрите на все изменённые строки. Удалённый текст выделен красным, а строки с ним начинаются с символа -. Добавленный текст отмечен зелёным фоном, а строки с ним начинаются с символа +. Внутри строки фактически измененный контент имеет чуть более темный зеленый фон, чем остальная часть строки.

    • В частности, если в PR есть сложное форматирование или он изменяет CSS, JavaScript или другие элементы сайта, вы можете просмотреть сайт, сгенерированный с этими изменениями в PR. Перейдите на вкладку Conversation и нажмите ссылку Details в проверке deploy/netlify в нижней части страницы. По умолчанию ссылка открывается в текущей вкладке браузера, поэтому чтобы потерять частичный отзыв, откройте ссылку в новой вкладке. Вернитесь на вкладку Files changed, чтобы продолжить проверку пулреквеста.
    • Убедитесь, что PR соответствует правилам содержания и оформления; если что-то не так, укажите на этом со ссылкой на раздел в руководстве.
    • Если у вас есть вопрос или вы хотите прокомментировать определённое изменение, наведите курсор мыши на строку и кликните на появившуюся сине-белую кнопку с иконкой +. Напишите свой комментарий и нажмите на кнопку Start a review.
    • Если вам нужно оставить больше одного комментария, сделайте это по аналогии с предыдущим шагом.
    • По соглашению, если вы видите небольшую проблему, не имеющей отношение к основному назначению PR, например, опечатку или лишний пробел, вы можете сообщить о ней, начав комментарий с nit:, чтобы автор знал, что это незначительная ошибка. Хотя это не означает, что автор пулреквеста может проигнорировать такие проблемы.

    • Когда вы всё проверили или у вас не осталось комментариев, прокрутите в верхнюю часть страницы и нажмите на кнопку Review changes. Далее кликните либо на Comment или Request Changes. Напишите краткий итог вашей проверки и добавьте соответствующие Prow-команды по одной на каждой строке в поле Review Summary. SIG Docs следует процессу проверки кода Kubernetes. Все ваши комментарии будут отправлены автору PR в виде одного уведомления.

      • Если вы считаете, что PR в хорошем состоянии, чтобы его принять, добавьте команду /approve в резюме вашей проверки.
      • Если PR не нуждается в дополнительном техническом рассмотрении, добавьте ещё команду /lgtm.
      • Если PR требуется дополнительный технический обзор, добавьте команду /assign и после неё укажите логин человека на GitHub, который должен сделать технический анализ. Посмотрите на поле рецензентов во вступительной (фронтальной) части вверху данного Markdown-файла, чтобы выяснить, кто может провести технический разбор пулреквеста.
      • Чтобы заблокировать слияние PR, используйте команду /hold. Она добавит метку do-not-merge/hold.
      • Если в PR нет конфликтов и есть метки lgtm и approve (и нет метки hold), то он автоматически объединиться.
      • Если PR имеет метки lgtm и/или approve, и появляются новые изменения, эти метки будут автоматически удалены.

      Посмотрите список доступных команд, которые можно использовать в PR.

    • Если вы ранее выбрали нажали на Request changes и затем автор PR решил все указанные проблемы, вы можете обновить статус проверки либо на вкладке Files changed, либо в нижней части вкладки Conversation. Обязательно укажите команду /approve и при необходимости выберите технических рецензентов, чтобы можно было объединить PR.

Редактирование PR другого человека

Добавление комментариев в PR — полезное дело, но могут быть случаи, когда нужно сделать коммит в пулреквест другого человека, а не просто оставить свой отзыв.

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

Используемый процесс зависит от того, нужно ли вам отредактировать файл, который уже изменен в PR, либо вам нужно отредактировать файл, который в PR не участвовал.

Вы не можете отредактировать чужой PR, если выполняется одно из условий:

  • Если автор PR отправил свою ветку непосредственно в репозиторий https://github.com/kubernetes/website/, то только рецензент с правом отправки изменений напрямую в репозиторий может вносить изменения в PR. Авторам следует открыть PR из ветки в своей копии репозитория.
  • Если автор PR явно запретил редактирование утверждающими, вы не сможете внести изменения в его PR, пока он не изменит эту настройку.

Если файл уже изменён в PR

Этот метод использует интерфейс GitHub. Вы можете использовать командную строку, если вам комфортнее работать в ней, даже если вам нужно изменить файл, который ранее редактировался в PR.

  1. Перейдите на вкладку Files changed.
  2. Прокрутите к блоку с файлом, который вы хотите отредактировать и нажмите на иконку с карандашом.
  3. Внесите изменения, напишите сообщение коммита в соответствующем поле под текстовым редактором и нажмите Commit changes.

После этого ваш коммит отправляется в ветку из PR (скорее всего, в копию репозитория автора), и теперь отображается в PR, а ваши изменения отражаются на вкладке Files changed. Оставьте комментарий, чтобы автор PR знал, что вы что-то сделали в PR.

Если автор использует командную строку, а не сайт GitHub для работы с этим PR, он должен получить изменения со своей копии репозитория и перебазировать свою локальную ветку на ветку своей копии, прежде чем заниматься своим PR.

Если файл ещё не был изменён в PR

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

  1. Узнайте URL-адрес копии репозитория автора пулреквеста. Вы можете найти его в нижней части вкладки Conversation. Найдите текст Add more commits by pushing to. Первая ссылка после этой надписи ведет на ветку, а вторая ссылка — на саму копию репозитория. Скопируйте вторую ссылку. Запомните название ветки, пригодится впоследствии.

  2. Добавьте копию репозитория как новый удаленный репозиторий. В терминале перейдите в директорию своей копии репозитория. Придумайте имя для удаленного репозитория (например, по имени логина автора на GitHub) и добавьте его, используя следующую команду:

      git remote add <name> <url-of-fork>

  3. Получите информацию о добавленном удаленном репозитории. Это действие не затронет локальные файлы, а только загрузит в вашу копии репозитория информацию о другой копии (например, ветки и теги).

      git remote fetch <name>

  4. Перейдите в ветку, полученную с удаленного репозитория. Эта команда не получится, если у вас локально уже есть ветка с таким же именем.

      git checkout <branch-from-PR>

  5. Внесите изменения и добавьте их через git add, а затем зафиксируйте их.

  6. Отправьте изменения в удаленный репозиторий автора.

      git push <remote-name> <branch-name>

  7. Откройте снова сайт GitHub и обновите страницу PR. Вы увидите ваши изменения. Добавьте комментарий для автора, чтобы он был в курсе, что вы изменили его PR.

Если автор использует командную строку, а не интерфейс на GitHub для работы над PR, ему нужно получить новые изменения из своей копии репозитоии и перебазировать свою локальную ветку на ветку своей копии репозитории, прежде чем снова заниматься собственным PR.

Работа из локальной копии

В случае изменений нескольких файлов, либо добавлением новых или перемещением старых, лучше работать из локальной копии Git-репозитория на компьютере, нежели чем использовать для этого GitHub. Следующие инструкции используют командую утилиту git, которая предполагается, что она уже установлена на вашем компьютере. Вы можете воспользоваться ими даже, если пользуетесь графическим Git-клиента.

Клонирование репозитория

Вам нужно только один раз клонировать репозиторий на каждом компьютере, на котором вы работаете с документацией Kubernetes.

  1. Создайте копию репозитория kubernetes/website на GitHub. В браузере перейдите по https://github.com/kubernetes/website и нажмите на кнопку Fork. После нескольких секунд вы будете автоматически перенаправлены на URL-адрес вашей копии, которая будет иметь следующий вид: https://github.com/<github_username>/website.

  2. В окне термина используйте команду git clone для получения копии репозитория.

      git clone git@github.com/<github_username>/website

    После выполнения этой команды в текущей рабочей директории появится новая директория website с содержимым вашего репозитория на GitHub. В данном случае удаленный репозиторий origin будет ссылаться на вашу копию репозитория.

  3. Перейдите в новую директорию website. Добавьте новый удалённый репозиторий kubernetes/website под именем upstream.

      cd website

  git remote add upstream https://github.com/kubernetes/website.git

  4. Проверьте ваши репозитории origin и upstream.

    git remote -v

    Output is similar to:

    origin  git@github.com:<github_username>/website.git (fetch)
origin  git@github.com:<github_username>/website.git (push)
upstream    https://github.com/kubernetes/website (fetch)
upstream    https://github.com/kubernetes/website (push)

Работа в локальном репозитории

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

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

Для получения дополнительной информации обратитесь к разделу Выбор правильной ветки.

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

  1. Когда вы работаете локально, есть три разные копии репозитория: local, upstream и origin. Получите данные по удалённым репозиториям origin и upstream. Эта команда очистит кеш удаленных репозиториях без фактического изменения каких-либо из копии.

      git fetch origin
  git fetch upstream

    Этот рабочий процесс отличается от того, который определен в сообществе GitHub. Здесь вам не нужно объединять вашу локальную копию master из репозитория upstream/master, прежде чем отправлять изменения в вашу копию. Этот шаг не требуется в kubernetes/website, потому что ваша ветка базируется на репозитории upstream.

  2. Создайте локальную рабочую ветку из наиболее подходящей ветки upstream-репозитория: upstream/dev-1.xx для разработчиков в конкретных версиях или upstream/master для всех остальных участников. В этом примере предполагается, что вы будете работать с ветки upstream/master. Так как ваша локальная ветка master не настроена для отслеживания изменений с upstream/master на предыдущем шаге, поэтому вам нужно явно создать свою ветку от upstream/master.

      git checkout -b <my_new_branch> upstream/master

  3. После переключения на новую ветку можно начать в ней работать в текстовом редакторе. Используйте команду git status , чтобы посмотреть измененные файлы.

  4. Когда вы закончите работу, зафиксируйте изменения. Сначала выполните команду git status, чтобы увидеть, какие изменения будут добавлены в коммит. В выводе этой команды есть две важные секции: Changes staged for commit и Changes not staged for commit. Файлы в последней секции, рядом с которыми есть надпись modified или untracked, необходимо добавить, если вы хотите, чтобы они попали в коммит. Для каждого файла, который нужно добавить, используйте команду git add.

      git add example-file.md

    Когда все изменённые файлы добавлены, зафиксируйте их с помощью команды git commit:

      git commit -m "Your commit message"

    Заметка: В сообщении коммита не указывайте идентификатор или URL-адрес ишью или пулреквеста на GitHub. Если вы это сделаете, на странице ишью или пулреквеста будет показана информация о коммите всякий раз, когда коммит будет появляться в новой Git-ветке. Вы можете сослаться на ишью и пулреквесты позже на сайте GitHub.

  5. При желании вы можете посмотреть, как ваши изменения будут выглядеть на сайте, если запустите сайт на вашей машине с помощью команды hugo. Посмотрите раздел Просмотр ваших изменений локально. Кроме этого, вы увидите свои изменения после создания пулреквеста.

  6. Перед тем, как открывать пулреквест с вашими изменениями вам для начала отправить в ветку удаленного репозитория, чем в данном случае является origin.

      git push origin <my_new_branch>

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

  7. Перейдите по адресу https://github.com/kubernetes/website в вашем браузере. GitHub определит и укажет вам, что вы загрузили новую ветку в свою копию, и поэтому предложит создать пулреквест. Заполните шаблон запроса.

    • Название должно быть не длиннее 50 символов и отражать краткий итог изменений.
    • Подробное описание должно содержать больше информации про исправление, включая строку типа Fixes #12345, если пулреквест решает проблему на GitHub. Это приведет к автоматическому закрытию указанной ишью после принятия пулреквеста.
    • Вы можете добавить метки или другие метаданные и назначить рецензентов. Смотрите страницу Сортировка и классификация ишью.

    Нажмите на кнопку Create pull request.

  8. Начнут выполняться автоматические тесты в зависимости от состояния сайта с вашими изменениями. Если какой-либо из тестов завершился неудачно, нажмите на ссылку Details для получения дополнительной информации. Если тест Netlify прошёл успешно, по ссылке Details вы можете найти предварительную версию сайта Kubernetes с внесенными вашими изменениями. Именно на ней рецензенты будут проверять ваши изменения.

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

    git commit -a --amend
    • -a: зафиксировать все изменения
    • --amend: изменить предыдущий коммит вместо создания нового

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

    Если вы используете git commit -m, как в шаге 4, вы сделаете новый коммит, а не измените исходный (предыдущий) коммит. Создание нового коммита означает, что вам нужно объединить свои коммиты до того, прежде чем пулреквест может быть объединен.

    Следуйте инструкциям в шаге 6, чтобы отправить новый коммит в удаленный репозиторий. После этого новое изменение отобразится в пулреквесте, а дальше снова запустятся тесты, а также произойдет новая сборка предварительной версии сайта на Netlify с последними изменениями.

  10. Если рецензент изменяет файлы в вашем пулреквесте, вам нужно получить новые изменения в вашей локальной копии, до того как снова начать что-то делать. Используйте команды ниже, чтобы обновить свою ветку (предполагается, что ветка уже получена с вашей копии репозитория).

      git fetch origin
  git rebase origin/<your-branch-name>

    После перебазирования вам нужно добавить флаг --force-with-lease, чтобы принудительно отправить новые изменения в ветке на вашу копию.

      git push --force-with-lease origin <your-branch-name>

  11. Может возникнуть конфликт, если кто-то, как и вы, изменил те же части файла в ветке, из которой была создана ваша ветка. Если пулреквест показывает, что есть конфликты, которые нужно разрешить, вы можете сделать это либо на сайте GitHub, либо исправить их локально.

    Сначала выполните шаг 10, чтобы актуализировать локальную ветку в соответствии с веткой в удаленном репозитории.

    Затем обновите репозиторий upstream и перебазируйте вашу ветку на ту, с которой она была создана, в данном случае это upstream/master.

      git fetch upstream
  git rebase upstream/master

    Если есть конфликты, которые Git не может разрешить автоматически, вы можете увидеть конфликтующие файлы с помощью команды git status. Отредактируйте каждый конфликтующий файл: найдите в них маркеры конфликта >>>, <<< и ===. Разрешение конфликта происходит путём удаления указанных маркеров конфликта. После это нужно добавить измененные файлы с помощью команды git add <filename> и продолжить перебазирование ветки, используя команду git rebase --continue. Когда всё зафиксировано в репозитории и не осталось неразрешенных конфликтов, команда git status покажет, что вы вышли из состояния перебазирования ветки и нет изменений для фиксации. На этом этапе вам осталось принудительно отправить ветку в свою копию репозитория, после чего на странице пулреквеста не должны быть конфликты.

  12. Если у вашего PR отображаются несколько сделанных коммитов после редактирования предыдущих коммитов, вам следует объединить эти несколько коммитов в один коммит, чтобы PR мог быть объединен. Проверить количество коммитов можно на вкладке Commits на странице PR или выполнив git log в терминале. Объединение коммитов (Squashing commits) — это одна из форм перебазирования.

    git rebase -i HEAD~<number_of_commits>

    Ключ -i сообщает git, что вы хотите сделать перебазирование в интерактивном режиме. В этом режиме вы сможете выбрать для git, какие коммиты нужно объединить в один. Например, в вашей ветке есть 3 коммита:

    12345 commit 4 (2 minutes ago)
6789d commit 3 (30 minutes ago)
456df commit 2 (1 day ago)

    Вам нужно объединить свои последние три коммита в один-единственный.

    git rebase -i HEAD~3

    Эта команда откроет редактор с таким содержимым:

    pick 456df commit 2
pick 6789d commit 3
pick 12345 commit 4

    Измените pick на squash у тех коммитов, которые вы хотите объединить, и проверьте, что коммит с выбранным pick находится сверху.

    pick 456df commit 2
squash 6789d commit 3
squash 12345 commit 4

    Сохраните и закройте редактор. Затем отправьте объединённый коммит в репозитории с помощью команды git push --force-with-lease origin <branch_name>.

Если у вас возникли проблемы с разрешением конфликтов или вы долго не можете что-то разрешить, что связано с вашим пулреквестом, обратитесь за помощью в Slack-канал #sig-docs или в список рассылки kubernetes-sig-docs.

Просмотр изменений локально

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

  1. Соберите образ локально:

      make docker-image

  2. После того. как образ kubernetes-hugo собран, вы можете использовать его для запуска сайта:

      make docker-serve

  3. В адресной строке браузера введите вставьте адрес localhost:1313. Hugo будет следить за изменениями файловой системы и пересобирать сайт по мере необходимости.

  4. Чтобы остановить локальный сайт Hugo, откройте снова терминал и введите Ctrl+C или просто закройте окно с терминалом.

  1. Установите версию Hugo, которая указана в файле website/netlify.toml.

  2. В терминале перейдите в корневую директорию вашей копии документации Kubernetes и введите следующую команду:

      hugo server

  3. В адресной строке браузера скопируйте localhost:1313.

  4. Чтобы остановить локальный сайт Hugo, откройте снова терминал и введите Ctrl+C или просто закройте окно с терминалом.

Сортировка и классификация ишью

Люди в SIG Docs отвечают только за сортировку и классификацию ишью, связанных с документацией. Вопросы и проблемы общего характера также хранятся в репозитории kubernetes/website.

Что вы делаете, когда сортируете ишью:

  • Проверить ишью
    • Убедитесь, что ишью связана с документацией сайта. Некоторые заявки можно быстро закрыть, ответив на вопрос или указав автору на ресурс. Подробности смотрите в разделе Заявки с помощью или отчёты об ошибке в коде.
    • Рассмотрите, насколько обоснованной является заявка. Добавьте метку triage/needs-information, если в ишью описано мало подробностей, чтобы ее можно было начать решать, либо если шаблон был неправильно заполнен. Закройте заявку, если она имеет метки lifecycle/stale и triage/needs-information.
  • Добавьте метку с приоритетом (см. руководство по сортировке заявок, где подробно определены метки)
    • priority/critical-urgent - заниматься нужно прямо сейчас
    • priority/important-soon - нужно выполнить в течение 3 months
    • priority/important-longterm - нужно сделать в течение 6 months
    • priority/backlog - решение можно быть отложено на неопределенный срок indefinitely; самый низкий приоритет; делать, когда будут свободны ресурсы
    • priority/awaiting-more-evidence - указание, что это возможно хорошая задача, которую нужно иметь на виду
  • Дополнительно вы можете добавить метку help или good first issue, если определенная заявка может быть решена человеком, мало знакомым с Kubernetes или SIG Docs. В качестве руководства обратитесь к файлу Help Wanted and Good First Issue Labels.
  • При желании примите сами участие в ишью и отправьте PR для ее решения (в частности если она может быстро разрешена или вы ранее выполняли нечто подобное).

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

Если у вас есть вопросы о про сортировку, спросите в Slack-канале #sig-docs или в списке рассылки kubernetes-sig-docs.

Добавление и удаление меток

Для добавления метки нужен комментарий, содержащий что-то вроде /<label-to-add> или /<label-category> <label-to-add>. Метка уже должна быть создана в репозитории. Если вы попытаетесь добавить несуществующую метку, команда проигнорируется.

Примеры:

  • /triage needs-information
  • /priority important-soon
  • /language ja
  • /help
  • /good-first-issue
  • /lifecycle frozen

Для удаления метки нужен комментарий с /remove-<label-to-remove> или /remove-<label-category> <label-to-remove>.

Примеры:

  • /remove-triage needs-information
  • /remove-priority important-soon
  • /remove-language ja
  • /remove-help
  • /remove-good-first-issue
  • /remove-lifecycle frozen

Список всех меток, используемых в Kubernetes, находится здесь. Не все метки используются группой SIG Docs.

Дополнительные сведения о метках

  • Ишью может иметь несколько ярлыков.
  • Некоторые метки в своём имени содержат слеш для группировки, это своего рода “подметки”. Например, существует множество меток sig/, например, sig/cli и sig/api-machinery (полный список).
  • Некоторые метки добавляются автоматически, в зависимости от метаданных файлов из ишью, либо от используемых в комментариях команд со слешем, а также от указанной информации в описании.
  • Новые метки могут добавляться вручную человеком, который сортировкой ишью (либо тем, кто создает ишью).
    • kind/bug, kind/feature и kind/documentation: баг (bug) — это проблема в текущем контенте или в функциональности, а возможность (feature) — запрос на добавление нового контента или функциональности. Метка kind/documentation используется редко.
    • Метки language/ja, language/ko и похожие языковые метки добавляются, если ишью относится к локализованному контенту.

Жизненный цикл ишью

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

lifecycle/stale: после 90 дней бездействия ишью автоматически помечается как устаревшая (stale). Такая заявка будет автоматически закрыта, если эта метка не будет удалена с помощью команды /remove-lifecycle stale.

lifecycle/frozen: заявка с данной меткой не будет считаться устаревшей после 90 дней отсутствия активности. Пользователь вручную добавляет эту метку к заявкам, которые должны оставаться открытыми значительно дольше 90 дней, например, у ишью с меткой priority/important-longterm.

Обработка специальных типов ишью

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

Дублирование заявок

Если для какой-нибудь проблемы есть одна или несколько открытых заявок, решение этой проблемы должно быть вынесено в одну заявку. Вам нужно решить, какую заявку оставить открытой (либо вовсе открыть новую ишью), перенести всю соответствующую информацию и указать связанные заявки. Затем для всех остальных похожих заявок добавьте метку с triage/duplicate и закройте их. Наличие только одной-единственной заявки поможет уменьшить путаницу и избежать дублирования работы над одной и той же проблемой.

Заявки про неработающие ссылки

В зависимости от того, где сообщается о неработающей ссылке, для решения этой проблемы требуются различные действия. Неработающие ссылки в API и документации Kubectl — это заявки, связанные с автоматизацией и поэтому их нужно отмечать меткой /priority critical-urgent, пока проблема не будет полностью проанализирована. Все остальные неработающие ссылки — это ишью, которым нужно заниматься вручную, поэтому им нужно добавить метку /priority important-longterm.

Заявки, связанные с блогом

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

Заявки с помощью или отчёты об ошибке в коде

Некоторые открытые заявки — это проблемы с основным кодом или просьбы с помощью, когда что-то (например, учебное руководство) не работает. Для заявок, не имеющих отношение к документации, закройте её, проставив метку triage/support и добавив комментарий с ресурсами, где можно найти помощь (Slack, Stack Overflow) и при необходимости укажите, где нужно открыть заявку, чтобы сообщить об ошибке в функциональности (вероятно, репозиторий kubernetes/kubernetes отлично подойдет для этого).

Пример ответа на запрос о помощи:

This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](http://slack.k8s.io/). You can also search
resources like
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.

You can also open issues for Kubernetes functionality in
 https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

Пример ответа на сообщение об ошибке в коде:

This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

Добавление документации для новой функциональности

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

Зачастую SIG-группа, ответственная за новую функциональность, представляют черновик документацию в виде пулреквеста в соответствующую ветку выпуска в репозитории kubernetes/website, а кто-то из команды SIG Docs могут сделать вычитку или отредактировать черновик напрямую.

Поиск информации о новой функциональности

Чтобы узнать о будущей функциональности, посетите еженедельную встречу sig-release (см. страницу Сообщество, чтобы быть в курсе предстоящих собраний) и отслеживайте документацию к новому релизу в репозитории kubernetes/sig-release. Каждый выпуск имеет поддиректорию в директории /sig-release/tree/master/releases/. Каждая директорию содержит график выхода новой версии, черновик с примечаниями к выпуску, а также документ, в котором перечислена команда, занимающаяся новым выпуском.

  • График выпуска содержит ссылки на все другие документы, встречи, протоколы собраний и этапы, связанные с выпуском. Он также содержит информацию о целях и сроках выпуска, а также о любых специальных процессах, используемых этом выпуске. В нижней части документа определены несколько терминов, связанных с выпуском.

Этот документ также содержит ссылку на лист отслеживания функциональности — это “официальный” способ узнать про новую функциональность, запланированной в выпуске.

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

  • Черновик примечаний к выпуску — хорошая отправная точка, где можно узнать чуть больше о конкретной функциональности, изменениях, устаревших возможностях и в целом что-то ещё о выпуске. Содержимое может обновляться до конца цикла выпуска, поэтому будьте начеку.

Лист отслеживания функциональности

В списке отслеживания функциональности для данного выпуска Kubernetes перечислена вся функциональность, запланированная для выпуска. Каждая строка содержит название возможности, ссылку на основную заявку GitHub, уровень стабильности (Alpha, Beta или Stable), группу SIG и ответственного лица за её реализацию, информацию про документацию, черновик примечания для выпуска, а также указание, была ли функциональность уже принята. Имейте в виду следующее:

  • Функциональность в состоянии Beta и Stable обычно имеет более высокий приоритет по сравнению с версией Alpha.
  • Трудно протестировать (и, следовательно, написать документацию) функциональности, которая не ещё принята или,по крайней мере, считается полнофункциональной в своем PR.
  • Определение, нужна ли документировать функциональности, производится вручную, и даже если у функциональности нет метки, что ей нужна документация, это не означает, это действительно так.

Документирование функциональности

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

После того, как вы выбрали функциональность для документирования/наблюдения, заявите об этом в Slack-канале #sig-docs, на еженедельной встрече sig-docs или напрямую в PR, отправленном SIG. Если вам дали добро, вы можете редактировать PR, используя один из способов, указанных в разделе Редактирование PR другого человека.

Если вам нужно написать новую тему, полезны следующие ссылки:

Члены SIG, участвующие в документировании новой функциональности

Если вы участник SIG-группы, кто разрабатывает новую функциональность для Kubernetes, вам нужно работать с документацией SIG, чтобы убедиться, что на момент новой версии написана документация для этой функциональности. Проверьте электронную таблицу с отслеживанием функциональности или присоединитесь в Slack-канал #sig-release, чтобы узнать информацию о сроках выхода. Некоторые крайние сроки касательно документации:

  • Docs deadline - Open placeholder PRs: откройте пулреквест в ветку release-X.Y в репозитории kubernetes/website с небольшим коммитом, который вы позже измените. Используйте команду Prow /milestone X.Y, чтобы назначить PR соответствующему этапу. Это уведомляет человека, который занимается документацией и ответственный за этот выпуск, что выходит документация для новой функциональности. Если функциональность не нуждается в каких-либо изменениях документации, убедитесь, что команда sig-release знает об этом, написав им сообщение в Slack-канале #sig-release. Если для функциональности нужна документация, но PR для этого ещё не создан, функциональность может быть удалена из этапа.
  • Docs deadline - PRs ready for review: теперь ваш PR должен содержать первый черновик документации для вашей функциональности. Не беспокойтесь о форматировании или всяких улучшениях. Просто опишите, что делает эта функциональность и как ее использовать. Участник из группы документации, управляющий выпуском новой версии, будет работать вместе с вами, чтобы подготовить контент для публикации. Если вашей функциональности нужна документация и первого черновика с документацией до сих пор нет, эта функциональность может быть удалена из этапа.
  • Docs complete - All PRs reviewed and ready to merge: если ваш PR еще не был объединен в ветку release-X.Y к заданному крайнему сроку, обратитесь за помощью к человеку, ответственному за выпуск новой версии. Если вашей функциональности требуется документация, но она ещё не сделана, функциональность может быть удалена из этапа.

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

Участие к других репозиториях

В проекте Kubernetes более 50 самостоятельных репозиториев. Многие из этих репозиториев хранят код или контент, который можно рассматривать как документацию, например, справочный текст для пользователях, сообщения об ошибках, пользовательский текст в справочниках API или даже комментарии кода.

Если вы видите текст и не знаете, откуда он берётся, вы можете использовать поиск GitHub по репозиториям организации Kubernetes, чтобы выяснить, где встречается этот текст. Это поможет вам определиться с тем, куда создать заявку или PR.

У каждого репозитория могут быть определены собственные процессы и правила. До того как открыть проблему или отправить PR, изучите файлы README.md, CONTRIBUTING.md и code-of-conduct.md в репозитории, если они есть.

Большинство репозиториев используют шаблоны для заявок и PR. Просмотрите некоторые открытые заявки и PR, чтобы понять, как устроена работа. Обязательно как можно более подробно заполните шаблоны при открытии заявок или PR.

Локализация контента

Английский является основным языком документации Kubernetes, однако мы хотим, чтобы у людей была возможность читать документацию на своём родном языке. Если вам комфортно писать на другом языке, особенно в теме программного обеспечения, вы можете помочь перевести документацию Kubernetes или помочь с существующим переводом. Посмотрите страницу Локализация и задайте вопрос в списке рассылки kubernetes-sig-docs или в канале #sig-docs на Slack, если вы хотите помочь.

Работа с локализованным контентом

Старайтесь соблюдать эти рекомендации по работе с переведенным контентом:

  • В PR должны быть изменения касающиеся только одного языка.

В каждом языке есть собственные рецензенты и утверждающие.

  • Рецензентам: убедитесь, что PR содержат изменения только на одном языке.

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

1

Что дальше

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

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