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

• 1: Участие для начинающих
• 2: Участие для продвинутых
• 3: Участие для опытных
• 4: Обзор оформления документации
• 4.1: Руководство по оформлению документации
• 4.2: Руководство по содержанию документации
• 4.3: Написание новой темы
• 4.4: Использование шаблонов страниц
• 4.5: Организация контента
• 4.6: Пользовательские макрокоды Hugo
• 5: Обзор справочной документации
• 5.1: Участие в основном коде Kubernetes
• 5.2: Руководство по быстрому старту
• 5.3: Генерация справочной документации для API Kubernetes
• 5.4: Генерация справочной документации для команд kubectl
• 5.5: Генерация справочных страниц для компонентов и инструментов Kubernetes
• 6: Локализация документации Kubernetes
• 7: Участие в SIG Docs

1 - Участие для начинающих

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

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

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

Документация Kubernetes написана на Markdown, обработана и развернута при помощи Hugo. Исходные файлы находятся на GitHub по адресу https://github.com/kubernetes/website. Основная часть документации хранится в директории /content/en/docs/. Часть справочной документации автоматически генерируется из скриптов в директории update-imported-docs/.

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

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

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

Документация Kubernetes поддерживается специальной группой (Special Interest Group, SIG) под названием SIG Docs. Мы общаемся с помощью канала Slack, списка рассылки и еженедельных видеозвонков. Будем рады новым участникам. Для получения дополнительной информации обратитесь к странице Участие в SIG Docs.

Руководящие принципы по содержанию

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

Правила оформления

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

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

Шаблоны страниц

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

Макрокоды Hugo

Документация Kubernetes с помощью Hugo конвертируется из формата разметки Markdown в HTML. Мы используем встроенные макрокоды Hugo, а также некоторые из своих собственных, созданных специально для документации Kubernetes. Посетите страницу Нестандартные макрокоды Hugo, чтобы узнать, как их использовать.

Мультиязычность

Исходные файлы документации доступны на нескольких языках в директории /content/. Каждый язык имеет свою собственную директорию с двухбуквенным кодом, определенным стандартомISO 639-1 standard. Например, исходники документации для английского языка хранится в директории /content/en/docs/.

Более подробную информацию про участие в работе над документацией на нескольких языках "Localize content" в промежуточном руководстве по добавлению.

Если вы заинтересованы в переводе документации на новый язык, посмотрите раздел "Локализация".

Создание хороших заявок

Любой, у кого есть аккаунт на GitHub, может создать заявку (issue, или отчет об ошибке) в документации Kubernetes. Если вы заметили какую-либо какую-либо ошибку, даже если вы не знаете, как её исправить, откройте ишью. Но не делайте этого, если нашли небольшую ошибку, например, опечатку, которую вы при желании можете исправить самостоятельно. В этом случае можете исправить ее вместо того, чтобы писать об этом.

Как создать заявку

• Для существующей страницы

  Если заметили проблему на существующей странице в документации Kubernetes, перейдите в конец страницы и нажмите кнопку Create an Issue. Если вы ещё не авторизованы в GitHub, сделайте это. После этого откроется страница с форма для создания нового запроса в GitHub с уже предварительно заполненным полями.

  При помощи разметки Markdown опишите как можно подробнее, что хотите. Там, где вы видите пустые квадратные скобки ([ ]), проставьте x между скобками. Если у вас есть предлагаемое решение проблемы, напишите его.

• Запросить новую страницу

  Если вы хотите добавить что-то новое, но вы не уверены, на какую страницу документации это сделать или считаете, что новая информация не вписывается в существующие страницы, всё равно создайте ишью. Вы можете либо перейти на страницу документации, куда, по вашему мнению, нужно добавить новую информацию и создать заявку прямо с этой страницы, либо перейти по адресу https://github.com/kubernetes/website/issues/new/ и написать что вы хотите там.

Как заполнить хорошую заявку

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

• Используйте шаблон ишью и заполните его как можно подробнее.
• Четко изложите суть вашего проблемы, как она сказывается на пользователях.
• Как можно меньше ограничьте охват изменений в вашей заявке. Задачи с большим объемом работы разбейте на более мелкие. Например, "Fix the security docs" не является проблемой, требующей немедленного решения, зато заявка с заголовком "Add details to the 'Restricting network access' topic", вероятно, такой является.
• Если проблема связана с другой заявкой или пулреквестом, вы можете указать сослаться на них, либо по его полному URL-адресу, либо по их номеру с #. Например, Introduced by #987654.
• Будьте уважительны и избегайте жалоб. Например, заголовок ишью "The docs about X suck" явно не несёт ничего полезного или чтобы на него реагировали. Нормы поведения также применяется к общению в GitHub-репозиториях Kubernetes.

Участие в дискуссиях SIG Docs

Команда SIG Docs общается следующими способами:

• Зарегистрируйтесь в Slack-канале Kubernetes, а затем присоединитесь к каналу #sig-docs, где мы в режиме реального времени обсуждаем всё, что связано с документацией. И не забудьте представиться!
• Подпишитесь на список рассылки kubernetes-sig-docs, где проходят более общие дискуссии и принимаются официальные решения.
• Участвуйте в еженедельной видеовстрече IG Docs, которая анонсируется в Slack-канале и списке рассылки. В данный момент эти встречи проводятся в Zoom, поэтому вам необходимо загрузить клиент Zoom или позвонить по телефону.

Заметка: Вы всегда можете узнать когда будет очередное еженедельное собрание SIG Docs в календаре собраний сообщества Kubernetes.

Улучшение существующего текста

Чтобы улучшить текущее содержимое документации, вам нужно открыть пулреквест (pull request, PR) после того, как вы сделаете копию (fork) оригинального репозитория. Эти два термина относятся к GitHub. Для начала работы, которая показана в этом разделе, вам не нужно знать всё про эти понятия, так как вы всё можете делать в своём браузере. Когда вы перейдете к продвинутому руководству участника документации, тогда вам понадобиться пополнить свои знания Git.

Примечание. Разработчики кода Kubernetes. Если вы документируете новую функцию для предстоящего выпуска Kubernetes, ваш процесс будет немного другим. См. Документирование функции для руководства по процессу и информации о сроках.

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

Подписание CLA-соглашения CNCF

Прежде чем внести вклад в код или документацию Kubernetes, вам обязательно следует прочитать руководство для участников и подписать лицензионное соглашение участника (Contributor License Agreement, CLA). Не переживайте — подписание не займет много времени!

Поиск задач для работы

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

Если вы хотите ещё не определились с тем, над чем хотите поработать, перейдите по адресу https://github.com/kubernetes/website/issues и найдите ишью с меткой good first issue (вы можете использовать эту ссылку для быстрого поиска). Прочитайте комментарии, чтобы убедиться что нет открытого пулреквеста для решения текущей ишью, а также, что никто другой не оставил комментарий, что он работает над этой задачей в последнее время (как правило, 3 дня). Добавьте комментарий, что вы хотели бы заняться решением этой задачи.

Выбор правильной ветки в Git

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

• Используйте ветку master для исправления ошибок в текущей документации, либо чтобы улучшить существующий текст.
• Используйте ветку master для документирования функциональности в текущей версии Kubernetes, для которой отсутствовала документация. Прежде всего вам нужно написать документацию на английском языке, а затем команды по переводам подхватят это изменение, чтобы актуализировать перевод.
• Если вы работаете над переводом, вам нужно следовать соглашению в этой конкретной локализации. Чтобы понять это, вы можете другие пулреквесты (подсказка: is:pr is:merged label:language/xx)
  • Некоторые команды локализации работают с пулреквестами, которые ориентированы на ветку master
  • Другие команды локализации работают с рядом долговечных веток, периодически сливая их в ветку master. Такая ветка именуется как dev-<version>-<language code>.<team milestone>, например, dev-release-1.24-ja.1.
• Если вы пишете или обновляете документацию к выпуску грядущего изменения, то вам необходимо знать мажорную и минорную версию Kubernetes, в которой это изменение впервые появится.
  • Например, если переключатель возможностей (feature gates) JustAnExample должен измениться с альфа-версии на бета-версию в следующей минорной версии, вам необходимо знать номер этой версии.
  • Найдите ветку выпуска, названную для этой версии. Например, функциональность, которая изменились в выпуске vrelease-1.24, будет документирована в ветке dev-release-1.24.

Если вы все еще не уверены, какую ветку выбрать, спросите в Slack-канале #sig-docs или посетите еженедельную встречу SIG Docs, чтобы внести ясность.

Отправка пулреквеста

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

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

2. Если вы ранее не делали копию репозитория документации Kubernetes, вам будет предложено это сделать. Создайте копию репозитория под своим логином GitHub, а не в организации, в которой вы состоите. URL-адрес копии репозитория будет выглядит как https://github.com/<username>/website, в случае у вас нет репозитория с таким же названием.

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

3. Откроется редактор GitHub для редактирования исходного файла в формате Markdown. Внесите свои изменения. Под редактором заполните форму Propose file change. Первое поле — краткое содержание вашего сообщения коммита, оно должно содержать не более 50 символов. Второе поле является необязательным, в нём вы можете подробно расписать суть ваших изменений.

   Заметка: Не ссылайте на другие ишью или пулреквесты на GitHub в сообщении коммита. Вы можете сослаться на них в тексте пулреквеста.

   Нажмите на кнопку Propose file change. Изменения в файле записываются в виде коммита в новой ветке вашей копии репозитория, которая автоматически будет иметь имя что-то вроде patch-1.

4. На следующей странице вам будут показаны различия в вашей ветке (поля выбора head fork и compare) с текущим состоянием оригинального репозитория (base fork) в основной ветке (base) (по умолчанию ветка master в репозитории kubernetes/website). Вы можете выбрать другое значение в полях выбора, но не делайте этого сейчас. Сравните различия и если всё верно, нажмите кнопку Create pull request.

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

5. Отобразится форма с заголовком Open a pull request. Название пулреквеста будет содержать краткое описание из сообщения коммита, хотя вы можете изменить его при необходимости. В описании пулреквеста будет остальная информация из сообщения коммита (если оно есть) и небольшой шаблон с текстом. Прочитайте текст шаблона и сделайте то, что там описано, а затем удалите этот шаблонный текст. Если вы добавите в описание пулреквест fixes #<000000> или closes #<000000>, где #<000000> - номер связанной заявки, то GitHub автоматически закроет указанную заявку при слиянии пулреквеста. Оставьте флажок Allow edits from maintainers отмеченным. Нажмите на кнопку Create pull request.

   Поздравляем! Ваш пулреквест добавлен в список пулреквестов.

   Через несколько минут вы сможете просмотреть версию сайта с изменениями в вашем пулреквесте. Перейдите в низ страницы пулреквеста на вкладке Conversation и там нажмите на ссылку Details рядом с проверкой deploy/netlify. По умолчанию она откроется в текущей вкладке.

   Заметка: Пожалуйста, открывайте пулреквест, изменения которого затрагивают только один язык. Например, если вам нужно одинаково изменить один и тот же пример кода в нескольких языках, откройте по отдельному пулреквесту для каждого языка.

6. Ожидайте, когда проверят ваш пулреквест. Как правило, рецензенты выбираются авматоматически ботом k8s-ci-robot. Если рецензент попросил изменить пулреквест, вы можете сделать это, если перейдёте на вкладку Files changed и щёлкните на иконку с карандашом на любом изменённом файле в вашем пулреквесте. Сохранение измененного файла оформляется в виде нового коммита в ветке, указанной в пулреквесте. Если вы ожидаете новую проверку изменений от рецензента, заранее попросите его об этом не более одного раза в 7 дней. Вы также можете зайти в Slack-канал #sig-docs — это хорошее место, где можно попросить проверку пулреквеста.

7. Если ваши изменения одобрены, то рецензент объединяет соответствующий пулреквест. Через несколько минут вы сможете сможете увидеть его в действии на сайте Kubernetes.

Это только один из способов отправить пулреквест. Если вы уже опытный пользователь Git и GitHub, вы можете вносить изменения, используя локальный GUI-клиент или Git из терминала вместо того, чтобы использовать интерфейс GitHub для этого. Некоторые основы использования Git-клиента из командной строки обсуждаются в руководстве для продвинутого участника.

Просмотр пулреквестов в документацию

Новички документации могут обозревать пулреквесты. Вы можете изучить кодовую базу и завоевать доверие к себе со стороны коллег-участников. Документация на английском — это первоисточник содержимого. Мы общаемся на английском языке во время еженедельных встреч и в объявлениях сообщества. Владение английским языком может быть разным, поэтому используйте простой и прямой язык в своих обзорах пулреквестов. Полезные обзоры фокусируются как на мелких деталях, так и на потенциальном влиянии изменений.

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

Рекомендации

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

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

1. Перейдите по URL-адресу https://github.com/kubernetes/website/pulls. Вы увидите список всех пулреквестов в репозиторий сайта Kubernetes и его документации.

2. По умолчанию открываются открытые пулреквесты (статус open), поэтому вы не увидите закрытых или принятых пулреквестов. Рекомендуется добавить дополнительный фильтр cncf-cla: yes, а также для вашей первой проверки пулреквеста неплохо применить ещё и size/S и size/XS. Метка с размером назначается автоматически в зависимости от количества изменённых строк кода в пулреквесте. Вы можете применить фильтры, используя поля выбора в верхней части страницы, либо воспользоваться этой ссылкой для просмотра небольших пулреквестов. Все фильтры объединены в логическое AND, поэтому у вас не получиться искать по меткам size/XS и size/S одновременно.

3. Перейдите на вкладку Files changed. Посмотрите изменения, внесенные в PR, а также изучите любые связанные задачи (если есть). Если вы видите ошибку, неточность или хотите внести улучшение, то наведите курсор на строку и щелкните на появившийся символ +.

   Вы можете написать комментарий, после чего нажать на кнопку Add single comment или Start a review. Как правило, лучше начать проверку (review), поскольку тогда вы сможете оставить несколько комментариев и уведомить автора PR только после завершения рецензирования, вместо того, чтобы упоминать его в каждом комментарии.

4. После окончания разбора пулреквеста, нажмите на кнопку Review changes вверху страницы. Вы можете подвести краткий итог своей проверки и выполнить одно из действий: просто прокомментировать, одобрить или запросить изменения. Новым участникам нужно всегда только комментировать (кнопка Comment) пулреквесты.

Спасибо за обзор пулреквеста! Если вы новенький в проекте, рекомендуется попросить кого-нибудь оценить ваш обзор пулреквеста. Slack-канал #sig-docs — отличное место для этого.

Написание постов в блоге

Любой может написать пост в блоге и отправить его на рассмотрение. Посты блога не должны носит коммерческий характер и должны отражать опыт, который может широко применён в сообществе Kubernetes.

Чтобы заявить о посте вы можете отправить его, используя форму блога Kubernetes, либо же выполнить следующие действия.

1. Подпишите CLA, если вы еще этого не сделали.
2. Изучите разметку Markdown у текущих постов блога в репозитории сайта.
3. Напишите свою статью в вашем любимом текстовом редакторе.
4. По ссылке из второго шага нажмите на кнопку Create new file. Скопируйте из своего редактора текст и вставьте в многострочное поле. Назовите файл так, чтобы он соответствовал предлагаемому заголовку статьи в блоге, но не указывайте дату в имени файла. Рецензенты блога будут работать с вами над окончательным именем файла и датой публикации записи.
5. Когда вы сохраните файл, начнётся описанный выше процесс принятия пулреквеста в GitHub.
6. Рецензент блога рассмотрит вашу статью и вместе с вами будет работать над ее улучшением. Когда запись в блоге будет одобрена, будет известна дата публикации вашей статьи.

Отправка примеров использования

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

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

Что дальше

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

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

1

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

Заметка: Некоторые задачи требуют использование 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) — это одна из форм перебазирования.

```bash
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.

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

• Hugo в контейнере
• Hugo на локальном компьютере

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

Люди в 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 будут терять актуальность со временем, поэтому мы поддерживаем записи, опубликованные в течение года. Если заявка сообщает о проблеме в записи блога, которой более одного года, ее следует закрыть без какого-либо исправления.

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

Некоторые открытые заявки — это проблемы с основным кодом или просьбы с помощью, когда что-то (например, учебное руководство) не работает. Для заявок, не имеющих отношение к документации, закройте её, проставив метку kind/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 для каждого языка.

Что дальше

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

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

На этой странице предполагается, что вы изучили темы Участие для начинающих и Участие для опытных и теперь хотите узнать ещё больше про то, как можно помочь проекту. Для решения некоторых задач вам потребуется использовать 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 и других конференциях
• Набирать персонал и выступать в поддержку CNCF и его платиновых партнеров, включая Google, Oracle, Azure, IBM и Huawei.
• Поддерживать нормальную работу SIG

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4 - Обзор оформления документации

Темы в этом разделе содержат рекомендации по написанию, форматированию и организации контента, а также охватывают настройку Hugo в контексте документации Kubernetes.

4.1 - Руководство по оформлению документации

На этой странице вы найдёте рекомендации по оформлению написания документации Kubernetes. Это рекомендации, а не правила. Используйте здравый смысл и не стесняйтесь предлагать изменения в этот документ в виде пулреквеста.

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

Заметка: В документации Kubernetes используется Blackfriday Markdown Renderer вместе с несколькими макрокодами Hugo для добавления поддержки записей глоссария, вкладок и отображения состояний функциональностей.

Язык

Документация Kubernetes была переведена на несколько языков (см. README-файлы локализаций).

Процесс локализации документации на другие языки описан в соответствующей странице по локализации.

Правила форматирования документации

Используйте верблюжью нотацию для написания объектов API

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

Не разделяйте имя объекта API на отдельные слова. Например, пишите PodTemplateList, а не Pod Template List.

Указывая имена API-объектов, не добавляйте к ним слово "объект", за исключением случаев, когда это только ухудшает читаемость.

Используйте угловые скобки для заполнителей

Используйте угловые скобки для заполнителей. Сообщите читателю, что означает заполнитель.

1. Отобразить информацию о Pod:

    kubectl describe pod <pod-name> -n <namespace>
   

   Если пространство имён пода равняется default, вы можете опустить параметр '-n'.

Используйте полужирное начертание для элементов пользовательского интерфейса

Используйте курсивное начертание для определения или включения новых терминов

Оформляйте как код имена файлов, директории и пути

Используйте международные правила для пунктуации внутри кавычек

Форматирование с использованием однострочного кода

Используйте оформление кода для встроенного кода и команд

Для однострочного (встроенного) блока кода в HTML-документе используйте тег <code>. В файле Markdown используйте обратную кавычку (`).

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

Имена полей объектов и пространства имён оформляйте как код

Имена компонентов и командного инструмента оформляйте как код

Начинайте предложение с имени инструмента или компонента

Используйте общее описание вместо имени компонента

Cтроковые и целочисленные значения полей пишите в обычном стиле

Для значений полей типа string или integer используйте обычный стиль без кавычек.

Форматирование фрагментов кода

Не добавляйте символ приглашения командной строки

Отделяйте команды от вывода

Убедитесь, что Pod работает на выбранном вами узле:

kubectl get pods --output=wide

Вывод будет примерно таким:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Версионирование примеров Kubernetes

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

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

Для указания версии Kubernetes для страницы задачи или руководства в фронтальную часть файла добавьте поле min-kubernetes-server-version.

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

Например, если вы пишете руководство, предназначенное для использования с версией Kubernetes 1.8, фронтальная часть вашего Markdown-файла должен выглядеть примерно так:

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

В примерах кода и конфигурации не добавляйте комментарии про альтернативные версии. Убедитесь в том, чтобы в комментариях ваших примеров не содержались некорректные сведения, такие как ниже:

apiVersion: v1 # в более ранних версиях...
kind: Pod
...

Словарь Kubernetes.io

Список специфичных для Kubernetes терминов и слов, которые будут регулярно встречаться по всему сайту.

Макрокоды

Макрокоды Hugo помогают создавать разного рода обращений к читателю. Наша документация поддерживает три разных макрокода для этого: примечание {{< note >}}, предостережение {{< caution >}} и предупреждение {{< warning >}}.

1. Заключите текст в открывающий и закрывающий макрокод.

2. Используйте следующий синтаксис для определения стиля:

   {{< note >}}
   Вам не нужно указывать надпись; макрокод автоматически добавит её. (Примечание:, Предостережение:, и т.д.)
   {{< /note >}}
   

Результат:

Заметка: Надпись блока будет такой же, как и имя тега.

Примечание

Используйте {{< note >}} для выделения подсказки или части информации, которая может быть полезна для ознакомления.

Например:

{{< note >}}
Вы _также_ можете использовать Markdown внутри этих выносок.
{{< /note >}}

Результат:

Заметка: Вы также можете использовать Markdown внутри этих выносок.

Вы можете использовать {{< note >}} в списке:

1. Используйте макрокод примечания в списке

1. Второй пункт с добавленным блоком примечания

   {{< note >}}
   Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел [Распространённые проблемы с шорткодами](#распространённые-проблемы-с-шорткодами).
   {{< /note >}}

1. Третий пункт в списке

1. Четвертый пункт в списке

Результат:

1. Используйте макрокод примечания в списке

2. Второй пункт с добавленным блоком примечания

   Заметка: Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел Распространённые проблемы с шорткодами.

3. Третий пункт в списке

4. Четвертый пункт в списке

Предостережение

Используйте {{< caution >}}, чтобы обратить внимание к важной информации, которая поможет избежать подводных камней.

Например:

{{< caution >}}
Оформление выноски применяется только к строке, следующей после тега выше.
{{< /caution >}}

Результат:

Внимание: Оформление выноски применяется только к строке, следующей после тега выше.

Предупреждение

Используйте {{< warning >}} для обозначения предупреждающей информации или такой, которую чрезвычайно важно соблюдать.

Например:

{{< warning >}}
Острожно.
{{< /warning >}}

Результат:

Предупреждение: Острожно.

Встраиваемая среда выполнения Katacoda

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

Встроенная среда выполнения сконфигурирована для выполнения команды minikube start и позволяет пользователям пройти руководство в той же самой вкладке, что и документация.

Внимание: Сессия ограничена 15 минутами.

Например:

{{< kat-button >}}

Результат:

Распространённые проблемы с шорткодами

Упорядоченные списки

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

Например:

1. Разогреть духовку до 350˚F

1. Подготовить тесто и вылить её в формочку для выпечки.
   {{< note >}}Для лучшего результата смажьте формочку.{{< /note >}}

1. Выпекать 20-25 minutes или пока тесто не зарумянится.

Результат:

1. Разогреть духовку до 350˚F

2. Подготовить тесто и вылить её в формочку для выпечки.

   Заметка: Для лучшего результата смажьте формочку.

3. Выпекать 20-25 minutes или пока тесто не зарумянится.

Выражения для вставок

Макрокоды внутри include-выражений нарушит процесс сборки. Поэтому они должны быть вставлены в родительский документ до и после вызова include. Например:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Элементы Markdown

Переносы строк

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

Заголовки

Люди, просматривающие документацию, могут использовать программу чтения с экрана или другую вспомогательную технологию (Assistive technologies, AT). Программы чтения с экрана — устройства вывода, которые выводят элементы на странице по очереди. Если на странице много текста, вы можете использовать заголовки, чтобы придать странице внутреннюю структуру. Хорошая структура страницы помогает всем читателям легко перемещаться по странице или выбрать интересующие темы.

Параграфы

Ссылки

Списки

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

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

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

• Используйте цифру один (1.) для упорядоченных списков.

• Используйте (+), (*) или (-) для неупорядоченных списков.

• Добавьте пустую строку после каждого списка.

• Во вложенных списках добавьте отступ в четыре пробела (например, ⋅⋅⋅⋅).

• Элементы списка могут содержать несколько абзацев. Каждый последующий абзац в элементе списка должен иметь отступ в четыре пробела или один символ табуляции.

Таблицы

Семантическая цель таблицы данных состоит в представлении данных в табличном виде. Пользователи с нормальным зрением могут бегло просмотреть таблицу, однако программа для чтения с экрана сканирует таблицу построчно. Заголовок таблицы используется для создания информативного заголовка для табличных данных. Инструменты вспомогательных технологий (Assistive technologies, AT) используют элемент заголовка HTML-таблицы, чтобы идентифицировать для пользователей, какие на странице есть таблицы.

• Добавьте подписи к таблицам с помощью соответствующих макрокодов Hugo.

Рекомендации по написанию контента

В этом разделе перечислены рекомендации для написания ясного, лаконичного и единообразного текста документации.

Используйте настоящее время

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

Используйте действительный залог

Исключение: используйте страдательный залог, если в действительном залоге получается неудачная формулировка.

Используйте простой и понятный язык

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

Обращайтесь к читателю на "вы"

Избегайте использования латинских фраз

Вместо латинских аббревиатур используйте соответствующие выражения на английском.

Исключение: используйте "etc." вместо "et cetera".

Ошибки, которые следует избегать

Избегайте использования "мы"

Использование "мы" в предложении может сбить с толку, так так неясно, кто под этим "мы" подразумевается (имеется ли в виду сам читатель при этом).

Избегайте жаргона и идиомы

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

Избегайте выражений о будущем

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

Избегайте выражений, которые могут потерять актуальность

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

Что дальше

• Подробнее про написание новой темы.
• Подробнее про использование шаблонов страниц.
• Подробнее про создание пулреквеста).

4.2 - Руководство по содержанию документации

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

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

Участие в контенте

Документация Kubernetes включает содержимое из оригинального репозитория kubernetes/website. Документация Kubernetes находится в директории kubernetes/website/content/<language_code>/docs, большая часть которой относится к проекту Kubernetes. Документация Kubernetes может также включать содержимое их проектов в GitHub-организациях kubernetes и kubernetes-sigs, если у этих проектов нет собственной документации. Всегда можно ссылаться на действующие проекты kubernetes, kubernetes-sigs и (CNCF) в документации Kubernetes, но перелинковка с продуктами определённого разработчика не допускается. Проверьте списки проектов CNCF (Graduated/Incubating, Sandbox, Archived), если вы не уверены в статусе CNCF проекта

Контент, полученный из двух источников

Документация Kubernetes не содержит дублированный контент, полученный из разных мест (так называемый контент из двумя источниками). Контент из двух источников требует дублирования работы со стороны мейнтейнеров проекта и к тому же быстро теряет актуальность. Перед добавлением контента, задайте себе вопрос:

• Новая информация относится к действующему проекту CNCF ИЛИ проекту в организациях на GitHub kubernetes или kubernetes-sigs?
  • Если да, то:
    • У этого проекта есть собственная документация?
      • если да, то укажите ссылку на документацию проекта в документации Kubernetes
      • если нет, добавьте информацию в репозиторий проекта (если это возможно), а затем укажите ссылку на неё в документации Kubernetes
  • Если нет, то:
    • Остановитесь!
      • Добавление информации по продуктам от других разработчиков не допускается
      • Не разрешено ссылаться на документацию и сайты сторонних разработчиков.

Разрешенная и запрещённая информация

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

1. Инструкции по установке или эксплуатации Kubernetes, которые не связаны с проектами Kubernetes

   • Разрешено:
     • Ссылаться на документацию на CNCF-проекта или на проект в GitHub-организациях kubernetes или kubernetes-sigs
       • Пример: для установки Kubernetes в процессе обучения нужно обязательно установить и настроить minikube, а также сослаться на соответствующую документацию minikube
     • Добавление инструкций для проектов в организации kubernetes или kubernetes-sigs, если по ним нет инструкций
       • Пример: добавление инструкций по установке и решению неполадок kubadm
   • Запрещено:
     • Добавление информацию, которая повторяет документацию в другом репозитории
       • Примеры:
         • Добавление инструкций по установке и настройке minikube; Minikube имеет собственную документацию, которая включают эти инструкции
         • Добавление инструкций по установке Docker, CRI-O, containerd и других окружений для выполнения контейнеров в разных операционных системах
         • Добавление инструкций по установке Kubernetes в промышленных окружениях, используя разные проекты: -Kubernetes Rebar Integrated Bootstrap (KRIB) — это проект стороннего разработчика, поэтому все содержимое находится репозитории разработчика.
           • У проекта Kubernetes Operations (kops) есть инструкции по установке и руководства в GitHub-репозитории.
           • У проекта Kubespray есть собственная документация
     • Добавление руководства, в котором объясняется, как выполнить задачу с использованием продукта определенного разработчика или проекта с открытым исходным кодом, не являющиеся CNCF-проектом или проектом в GitHub-организациях kubernetes или kubnetes-sigs.
     • Добавление руководства по использованию CNCF-проекта или проекта в GitHub-организациях kubernetes или kubnetes-sigs, если у проекта есть собственная документация

2. Подробное описание технических аспектов по использованию стороннего проекта (не Kubernetes) или как этот проект разработан

   Добавление такого типа информации в документацию Kubernetes не допускается.

3. Информация стороннему проекту

   • Разрешено:
     • Добавление краткого введения о CNCF-проекте или проекте в GitHub-организациях kubernetes или kubernetes-sigs; этот абзац может содержать ссылки на проект
   • Запрещено:
     • Добавление информации по продукту определённого разработчика
     • Добавление информации по проекту с открытым исходным кодом, который не является CNCF-проектом или проектом в GitHub-организациях kubernetes или kubnetes-sigs
     • Добавление информации, дублирующего документацию из другого проекта, независимо от оригинального репозитория
       • Пример: добавление документации для проекта Kubernetes in Docker (KinD) в документацию Kubernetes

4. Только ссылки на сторонний проект

   • Разрешено:
     • Ссылаться на проекты в GitHub-организациях kubernetes и kubernetes-sigs
       • Пример: добавление ссылок на документацию проекта Kubernetes in Docker (KinD), который находится в GitHub-организации kubernetes-sigs
     • Добавление ссылок на действующие CNCF-проекты
       • Пример: добавление ссылок на документацию проекта Prometheus; Prometheus — это действующий проект CNCF
   • Запрещено:
     • Ссылаться на продукты стороннего разработчика
     • Ссылаться на архивированные проекты CNCF
     • Ссылаться на недействующие проекты в организациях GitHub в kubernetes и kubernetes-sigs
     • Ссылаться на проекты с открытым исходным кодом, которые не являются проектами CNCF или не находятся в организациях GitHub kubernetes или kubernetes-sigs.

5. Содержание учебных курсов

   • Разрешено:
     • Ссылаться на независимые от разработчиков учебные курсы Kubernetes, предлагаемыми CNCF, Linux Foundation и Linux Academy (партнер Linux Foundation)
       • Пример: добавление ссылок на курсы Linux Academy, такие как Kubernetes Quick Start в Kubernetes Security
   • Запрещено:
     • Ссылаться на учебныЕе онлайн-курсы, вне CNCF, Linux Foundation или Linux Academy; документация Kubernetes не содержит ссылок на сторонний контент
       • Пример: добавление ссылок на учебные руководства или курсы Kubernetes на Medium, KodeKloud, Udacity, Coursera, learnk8s и т.д.
     • Ссылаться на руководства определённых разработчиков вне зависимости от обучающей организации
       • Пример: добавление ссылок на такие курсы Linux Academy, как Google Kubernetes Engine Deep Dive and Amazon EKS Deep Dive

Если у вас есть вопросы по поводу допустимого контента, присоединяйтесь к каналу #sig-docs в Slack Kubernetes!

Что дальше

• Прочитайте руководство по оформлению.

4.3 - Написание новой темы

На этой странице показано, как создать новую тему для документации Kubernetes.

Подготовка к работе

Создайте копию репозитория документации Kubernetes, как описано в разделе Участие для начинающих.

Выбор типы страницы

Перед написанием новой темы, выберите тип страницы, который бы лучше всего подходил под ваш текст:

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

Выбор заголовка и имени файла a title and filename

Подберите заголовок, содержащий такие ключевые слова, по которым вы могли его найти в поисковике. Имя файла должно создаваться из слов в заголовке, написанных через дефис. Например, для темы с заголовком Using an HTTP Proxy to Access the Kubernetes API имя файла будет http-proxy-access-api.md. Вам не нужно указывать "kubernetes" в имени файла, потому что слово "kubernetes" уже есть в полном URL-адресе темы, например:

   /docs/tasks/access-kubernetes-api/http-proxy-access-api/

Добавление заголовка темы в фронтальную часть

В фронтальную часть файла вашей темы поместите поле заголовка title. Фронтальная часть — YAML-блок, который находится тремя дефисами в самом верху страницы. Например:

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

Выбор директории

В зависимости от типа вашей страницы поместите новый файл в одну из следующую поддиректорию:

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

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

Добавление темы в оглавлении

Оглавление динамически генерируется исходя из структуры директорий документации. Корневые директории в /content/en/docs/ создают навигацию с основными ссылками, где у каждой поддиректории есть записи в оглавлении.

В каждой поддиректории есть файл _index.md, представляющий собой "главную" страницу всего содержимого этой поддиректории. В файле _index.md не нужно применять шаблон. В нём находится обзор содержания тем в поддиректории.

Другие файлы в директории по умолчанию сортируются в алфавитном порядке. Такой порядок сортировки редко устраивает. Для управления такой относительной сортировкой тем в поддиректории, определите ключ weight: с целым числом в фронтальной части файла. Как правило, мы используем значения, кратные 10, чтобы оставить про запас для будущих страниц. Например, тема с весом 10 будет отображаться перед темой с весом 20.

Вставка кода в тему

Если вы хотите добавить код в тему, вы можете встроить код из файла напрямую, используя синтаксис блока кода в Markdown. Такой способ рекомендуется использовать в следующих случаев (это не исчерпывающий список):

• В вашем коде показывается вывод такой команды, как kubectl get deploy mydeployment -o json | jq '.status'.
• Ваш код недостаточно универсален, чтобы пользователи могли его попробовать сами. В качестве примера можно привести пример YAML-файла для создания Pod, который зависит от конкретной реализации FlexVolume.
• Ваш код — это не готовый пример, потому что он предзначен для выделения части большего файла. Например, при описании способов настройки PodSecurityPolicy по определённым причинам вы можете включить небольшой фрагмент напрямую в файле темы.
• Ваш код по разным причинам не подходит для тестирования пользователями. Например, если вы описываете, как новый атрибут должен добавляться к ресурсу с помощью команды kubectl edit, то вы можете добавить короткий пример, показывающий только добавляемый атрибут.

Добавление кода из другого файла

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

При добавлении нового отдельного файла примера, например, в формате YAML, поместите код в одну из директорий <LANG>/examples/, где <LANG> — язык темы. В вашем файле темы используйте макрокод codenew:

{{< codenew file="<RELPATH>/my-example-yaml>" >}}

где <RELPATH> — это путь к включаемому файлу относительно директории examples. Следующий макрокод Hugo ссылается на YAML-файл по пути /content/en/examples/pods/storage/gce-volume.yaml.

{{< codenew file="pods/storage/gce-volume.yaml" >}}

Заметка: Чтобы отобразить Hugo-макрокоды в исходном виде, как в приведенном выше примере, поместите их в комментарии в стиле языка Си между < и >. Для примера посмотрите исходный код этой страницы.

Демонстрация создания API-объекта из конфигурационного файла

Если вам нужно показать, как создать объект API из файла конфигурации, поместите файл конфигурации в одну из директорий в <LANG>/examples.

В вашей теме укажите эту команду:

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

Заметка: При добавлении новых YAML-файлов в директорию <LANG>/examples, убедитесь, что этот файл перечислен в файле <LANG>/examples_test.go. Подключённый к сайту Travis CI автоматически выполнит этот тестовый сценарий при отправке PR, чтобы проверить все примеры.

В качестве примера темы, в которой используется этот метод, смотрите Running a Single-Instance Stateful Application.

Добавление изображений в тему

Поместите файлы изображений в директорию /images. Предпочтительный формат изображения — SVG.

Что дальше

• Подробнее про использование шаблонов страниц.
• Подробнее про создание пулреквеста).

4.4 - Использование шаблонов страниц

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

Шаблоны страниц находятся в директории layouts/partials/templates репозитория kubernetes/website.

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

Шаблон концепции

Страница концепции объясняет некоторые аспекты Kubernetes. Например, страницы концепции может описывать объект Deployment в Kubernetes и разъяснить какую роль он играет после развертывания, масштабирования и обновления приложения. Как правило, страницы концепций не включают последовательности шагов, и вместо этого содержат ссылки на задачи или руководства.

Для написания новой страницы концепции в директории /content/en/docs/concepts создайте поддиректорию с Markdown-файлом со следующим требованиями:

• Во фронтальной части YAML этой страницы определите поле content_type: concept.

• В теле страницы укажите переменные capture и любые другие, которые вы хотите включить:

  Переменная	Обязательна?
  overview	да
  body	да
  whatsnext	нет

  Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не понадобятся):

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture body %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Заполните каждый раздел информацией. Следуйте этим рекомендациям:

  • Структурируйте контент с помощью заголовков H2 и H3.
  • В блоке overview одним абзацем сформируйте контекст темы.
  • В блоке body объясните суть концепции.
  • В блоке whatsnext сформируйте ненумерованный список тем (до 5), к которым нужно обратиться, чтобы получить дополнительную информацию о концепции.

Annotations — это готовый пример шаблона концепции. Кстати, текущая страница использует шаблон концепции.

Шаблон задачи

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

Для написания новой страницы задачи в директории /content/en/docs/tasks создайте поддиректорию с Markdown-файлом со следующим требованиями:

• Во фронтальной части YAML этой страницы определите поле content_type: task.

• В теле страницы укажите переменные capture и любые другие, которые вы хотите включить:

  Переменная	Обязательна?
  overview	да
  prerequisites	да
  steps	нет
  discussion	нет
  whatsnext	нет

  Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не нужны):

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture prerequisites %}}
  
  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  
  {{% /capture %}}
  
  {{% capture steps %}}
  
  {{% /capture %}}
  
  {{% capture discussion %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Заполните каждый блок информацией. Следуйте этим рекомендациям:

  • Используйте по минимуму заголовков H2 (с двумя ведущими символами #). У самих разделов заголовок формируется автоматически по заданному шаблону.
  • В блоке overview обозначьте контекст для всей темы.
  • В блоке prerequisites используйте ненумерованные списки, где это возможно. Добавьте дополнительные предварительные условия ниже include. Предварительные условия по умолчанию содержат пункт про наличие работающего кластера.
  • В блоке steps используйте нумерованные списки.
  • В блоке discussion подробно распишите информацию, описанную в разделе steps.
  • В блоке whatsnext сформируйте ненумерованный список тем (до 5), которые могут быть интересны читателю в качестве дополнительного чтения.

Пример готовой темы, в которой используется шаблон задачи — Using an HTTP proxy to access the Kubernetes API.

Шаблон руководства

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

Для написания новой страницы задачи в директории /content/en/docs/tutorials создайте поддиректорию с Markdown-файлом со следующим требованиями:

• Во фронтальной части YAML этой страницы определите поле content_type: tutorial.

• В теле страницы укажите переменные capture и любые другие, которые вы хотите включить:

  Переменная	Обязательна?
  overview	да
  prerequisites	да
  objectives	да
  lessoncontent	да
  cleanup	нет
  whatsnext	нет

  Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не понадобятся):

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture prerequisites %}}
  
  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  
  {{% /capture %}}
  
  {{% capture objectives %}}
  
  {{% /capture %}}
  
  {{% capture lessoncontent %}}
  
  {{% /capture %}}
  
  {{% capture cleanup %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Заполните каждый блок информацией. Следуйте этим рекомендациям:

  • Используйте по минимуму заголовков H2 (с двумя ведущими символами #). У самих разделов заголовок формируется автоматически по заданному шаблону.
  • В блоке overview обозначьте контекст для всей темы.
  • В блоке prerequisites используйте ненумерованные списки, где это возможно. Добавьте дополнительные предварительные условия ниже include. Предварительные условия по умолчанию содержат пункт про наличие работающего кластера.
  • В блоке objectives используйте ненумерованные списки.
  • В блоке lessoncontent целесообразно используйте совместно нумерованные списки и повествовательное содержание.
  • В блоке cleanup используйте нумерованные списки для описания шагов для очистки состояния кластера после выполнения задачи.
  • В блоке whatsnext сформируйте ненумерованный список тем (до 5), которые могут быть интересны читателю в качестве дополнительного чтения.

Пример завершенной темы, в которой используется шаблон руководства — Running a Stateless Application Using a Deployment.

Что дальше

• Подробнее про оформление документации
• Подробнее про содержание документации
• Подробнее про организацию контента

4.5 - Организация контента

Этот сайт использует Hugo. В Hugo организация контента — основная концепция.

Заметка: Подсказка: при редактировании контента используйте команду hugo server --navigateToChanged, чтобы запустить Hugo.

Списки страниц

Порядок страницы

Меню в сайдбаре, каталог страниц документации используют стандартный порядок перечисления Hugo, который сортирует элементы по весу (от 1), дате (начиная с самых новых) и затем по заголовку ссылки.

Таким образом, если вам нужно поднять страницу или раздел, определите её вес в фронтальной части:

title: Моя страница
weight: 10

Заметка: Для значений веса страниц лучше не использовать привычный порядок 1, 2, 3..., а предпочесть другой интервал, например, 10, 20, 30... В будущем это позволит вставить последующие страницы в желаемую позицию.

Главное меню документации

Главное меню Документация состоит из разделов по пути docs/ с установленным флагом main_menu в фронтальной части файла раздела _index.md:

main_menu: true

Обратите внимание, что текст ссылки берётся из переменной linkTitle, поэтому, если вы хотите, чтобы он отличался от заголовка страницы, измените его в файле:

main_menu: true
title: Название страницы
linkTitle: Название, которое будет использоваться в ссылках

Заметка: Перечисленные выше переменные должны быть определены для каждого перевода. Если вы не видите созданный вами раздел в меню, скорее всего, это может быть связано с тем, что Hugo не определил его как раздел. Создайте файл _index.md в директории раздела.

Документация в боковом меню

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

Оно отобразит все разделы и их страницы.

Если вы хотите, чтобы раздел или страница не отображались в меню, установите для флага toc_hide значение true в фронтальной части файла:

toc_hide: true

При переходе к непустому разделу будет отображаться указанный раздел или страница (например, _index.md). В противном случае выводиться первая страница в этом разделе.

Каталог документации

Каталог страниц на главной странице документации сгенерирован с учётом всех разделов и страниц документации.

Если вы хотите скрыть раздел или страницу, установите для флага toc_hide значение true в фронтальной части файла:

toc_hide: true

Главное меню

Ссылки сайта в верхнем правом меню, а также в футере, создаются посредством сканирования страниц. Этот процесс гарантирует, что страница действительно существует на сайте. Поэтому, если раздела case-studies на сайте (или в переводе) не существует, ссылка не появится.

Пакеты страниц

В дополнение к отдельным страницам с контентом (Markdown-файлам), Hugo поддерживает пакеты страниц (page bundles).

К примеру, пользовательские макрокоды Hugo — узел пакета (leaf bundle). Все, что находится в директории, включая index.md, будет частью пакета. Сюда также относятся относительные ссылки на страницы, изображения, которые могут быть обработаны и т.д.:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Другой распространённый пример — это пакет includes. Он устанавливает переменную headless: true, которая означает, что файл не будет доступен по собственному URL-адресу. Вместо этого он будет использоваться в других страницах как вставляемый файл.

en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Необходимо отметить следующие особенности файлов в пакетах:

• Для переведенных пакетов любые отсутствующие файлы будут унаследованы от файлов на оригинальном (английском) языке. Это позволяет избежать дублирования.
• Все файлы в пакете — в Hugo называются ресурсы (Resources), в которых вы можете определить метаданные, зависимые от языка, например, параметры и заголовок, даже если они не поддерживают в фронтальной части (YAML-файлы и т.д.). Смотрите Метаданные ресурсов страницы для получения дополнительной информации.
• Значение, которое вы получаете через .RelPermalink в Resource будет отличаться в зависимости от страницы. Смотрите Постоянные ссылки для получения дополнительной информации.

Стилизация

Исходные файлы стилей в формате SASS находятся в директории assets/sass и автоматически собираются Hugo.

Что дальше

• Подробнее про пользовательские макрокоды Hugo
• Подробнее про оформление документации
• Подробнее про содержание документации

4.6 - Пользовательские макрокоды Hugo

На этой странице объясняются пользовательские макрокоды Hugo, которые можно использовать в Markdown-файлах документации Kubernetes.

Узнать подробнее про макрокоды можно в документации Hugo.

Состояние функциональности

В Markdown странице (файл с расширением .md) вы можете добавить макрокод, чтобы отобразить версию и состояние документированной функциональной возможности.

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

Ниже показан фрагмент кода для вывода состояния функциональности, который сообщает о функциональности в стабильной версии Kubernetes 1.10.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Результат:

Допустимые значения для state:

• alpha
• beta
• deprecated
• stable

Код состояния функциональности

По умолчанию отображается версия Kubernetes, соответствующая версии страницы или сайта. Это значение можно переопределить, передав параметр макрокода for_k8s_version.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Результат:

Функциональность в альфа-версии

{{< feature-state state="alpha" >}}

Результат:

Функциональность в бета-версии

{{< feature-state state="beta" >}}

Результат:

Функциональность в стабильной версии

{{< feature-state state="stable" >}}

Результат:

Устаревшая функциональность

{{< feature-state state="deprecated" >}}

Результат:

Глоссарий

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

Исходные файлы терминов глоссария хранятся в отдельной директории по URL-адресу https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary.

Демонстрация глоссария

Например, следующий фрагмент кода в Markdown будет отображен в виде всплывающей подсказки — cluster:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Заголовки таблиц

Для улучшения доступности таблиц для программ для чтения с экрана, добавьте заголовок к таблице. Чтобы добавить заголовок таблицы, поместите таблицу в макрокод table и определите значение заголовка в параметре caption.

Заметка: Заголовки таблиц предназначены только для программ чтения с экрана, поэтому в браузере они не будут отображаться.

Пример:

{{< table caption="Конфигурационные параметры" >}}
Параметр | Описание | Значение по умолчанию
:---------|:------------|:-------
`timeout` | Тайм-аут для запросов | `30s`
`logLevel` | Уровень логирования | `INFO`
{{< /table >}}

Результат:

{{< table caption="Конфигурационные параметры" >}}

Если вы изучите HTML-код таблицы, вы заметите следующий ниже элемент сразу после открывающего элемента <table>:

<caption style="display: none;"></caption>

Вкладки

Страница в формате Markdown (файл с расширением .md) на этом сайте может содержать набор вкладок для отображения нескольких разновидностей определённого решения.

Макрокод tabs принимает следующие параметры:

• name: имя, отображаемое на вкладке.
• codelang: если вы указываете встроенный контент для макрокода tab, вы можете сообщить Hugo, какой язык использовать для подсветки синтаксиса.
• include: включаемый файл в вкладку. Если вкладка находится в узле пакета (leaf bundle) Hugo, то файл (может быть любым MIME-типом, который поддерживает Hugo) ищется в самом пакете. Если нет, то включаемое содержимое ищется относительно текущей страницы. Обратите внимание, что при использовании include вам следует использовать самозакрывающийся синтаксис. Например, {{</* tab name="Content File #1" include="example1" />}}. Язык может быть указан в codelang, в противном случае язык определяется из имени файла.
• Если содержимое вкладки это Markdown, вам нужно использовать символ %. Например, {{% tab name="Вкладка 1" %}}This is **markdown**{{% /tab %}}
• Вы можете совместно использовать перечисленные выше параметры. Ниже приведена демонстрация шорткода вкладок.

Ниже приведены примеры вкладок.

Заметка: Имя вкладки в элементе tabs должно быть уникальным на странице.

Демонстрация вкладок: подсветка синтаксиса в блоках кода

{{< tabs name="tab_with_code" >}}
{{{< tab name="Вкладка 1" codelang="bash" >}}
echo "Это вкладка 1."
{{< /tab >}}
{{< tab name="Вкладка 2" codelang="go" >}}
println "Это вкладка 2."
{{< /tab >}}}
{{< /tabs >}}

Результат:

• Вкладка 1
• Вкладка 2

echo "Это вкладка 1."

println "Это вкладка 2."

Демонстрация вкладок: встроенный Markdown и HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
Это **разметка Markdown.**
{{< note >}}
Также можно использовать макрокоды.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Обычный HTML</h3>
	<p>Это <i>обычный</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Результат:

• Markdown
• HTML

Демонстрация вкладок: включение файлов

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Результат:

• Content File #1
• Content File #2
• JSON File

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

Что дальше

• Подробнее про Hugo.
• Подробнее про написание новой темы.
• Подробнее про использование шаблонов страниц.
• Подробнее про создание пулреквеста.

5 - Обзор справочной документации

Темы в этом разделе описывают, как генерировать справочные руководства Kubernetes.

Для сборки справочной документации посмотрите следующий ресурс:

• Краткое руководство по генерации справочной документации

5.1 - Участие в основном коде Kubernetes

На этой странице показано, как поучаствовать в основном содержимом проекта kubernetes/kubernetes. Вы можете исправить баги, найденные в документации по API Kubernetes или содержимом таких компонентов Kubernetes, как kubeadm, kube-apiserver и kube-controller-manager.

Если вместо этого вы хотите перегенерировать справочную документацию для API Kubernetes или компонентов с именем kube-* в основном коде, изучите следующие инструкции:

• Генерация справочной документации для API Kubernetes
• Генерация справочной документации для компонентов и инструментов Kubernetes

Подготовка к работе

• Установленные инструменты:

  • Git
  • Golang версии 1.13+
  • Docker
  • etcd

• Созданная переменная окружения GOPATH, а путь к etcd должен быть прописан в переменной окружения PATH.

• Вам необходимо знать, как создать пулреквест в репозитории на GitHub. Это обычно предполагает создание копии репозитория. Для получения дополнительной информации смотрите страницы Создание пулреквеста и Стандартный рабочий процесс в GitHub по работе с копией и пулреквестом.

Рассмотрение процесса в целом

Справочная документация для API Kubernetes и таких компонентов с kube-*, как kube-apiserver, kube-controller-manager, автоматически генерируются из исходного кода в основном репозитории Kubernetes.

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

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

Если вы ещё не склонировали репозиторий kubernetes/kubernetes, сделайте это:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Определите базовую директорию вашей копии репозитория kubernetes/kubernetes. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/kubernetes/kubernetes. В остальных команд базовая директория будет именоваться как <k8s-base>.

Определите базовую директорию вашей копии репозитория kubernetes-sigs/reference-docs. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/kubernetes-sigs/reference-docs. В остальных команд базовая директория будет именоваться как <rdocs-base>.

Редактирование исходного кода Kubernetes

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

Документация для компонентов kube-* также генерируется из основного исходного кода. Для изменения генерируемой документации вам нужно изменить соответствующий код компонента.

Внесение изменений в основной исходный код

Заметка: Следующие шаги служат примером, а не общим порядком действий. Детали могут отличаться в вашей ситуации.

Рассмотрим пример редактирования комментария в исходном коде Kubernetes.

В вашем локальном репозитории kubernetes/kubernetes переключитесь на ветку master и проверьте, что она актуальна:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Предположим, что в исходном файле в ветке master есть опечатка "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

В вашем локальном окружении откройте types.go и измените "atmost" на "at most".

Убедитесь, что вы изменили файл:

git status

Вывод этой команды покажет, что вы находитесь в ветке master и был изменён исходный файл types.go:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Фиксация отредактированного файла

Выполните команду git add и git commit, чтобы зафиксировать внесенные вами изменения. На следующем шаге вы сделаете второй коммит. Следует отметить, что ваши изменения должны быть разделены на коммита.

Генерация спецификации OpenAPI и сопутствующих файлов

Перейдите в директорию <k8s-base> и выполните следующие скрипты:

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Выполните команду git status, чтобы посмотреть, какие файлы изменились.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Изучите содержимое файла api/openapi-spec/swagger.json, чтобы убедиться в том, что опечатка была исправлена. Например, для этого вы можете выполнить команду git diff -a api/openapi-spec/swagger.json. Это важно, потому что изменённый файл swagger.json является результатом второй стадии процесса генерации документации.

Выполните команду git add и git commit для фиксации ваших изменения. Теперь вы можете увидеть два новых коммита: первый содержит отредактированный файл types.go, а второй — сгенерированную спецификацию OpenAPI и сопутствующие файлы. Оформляйте эти изменения в виде двух отдельных коммитов. Это означает, что не нужно объединять коммиты.

Отправьте свои изменения как пулреквест в ветку master репозитория kubernetes/kubernetes. Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят.

PR 57758 — пример пулреквеста, который исправляет опечатку в исходном коде Kubernetes.

Заметка: Не всегда легко правильно определить, какой исходный файл нужно изменить. В предыдущем примере нужный исходный файл находится в директории staging в репозитории kubernetes/kubernetes. Однако в вашей ситуации файл для изменения может находится в другом месте, нежели чем в директории staging. Для получения помощи изучите файлы README в репозитории kubernetes/kubernetes и в смежных репозиториях, например, kubernetes/apiserver.

Применение вашего коммита в ветку выпуска

В предыдущем разделе вы отредактировали файл в ветке master, а затем запустили скрипты для генерации спецификации OpenAPI и смежных файлов. Затем вы отправили свои изменения в виде пулреквеста в ветку master репозитория kubernetes/kubernetes. Теперь представим, что вам нужно бэкпортировать изменения в ветку выпуска. К примеру, ветка master используется для разработки Kubernetes версии 1.10, а вы хотите применить ваши изменения в ветке release-1.9.

Напомним, что в вашем пулреквесте есть два коммита: первый для редактирования types.go, а второй — для файлов, сгенерированных скриптами. Следующий шаг — применить сделанный вами первый коммит в ветку release-1.9. Суть в том, чтобы выбрать коммит, который изменяет файл types.go, а не коммит с результатами выполнения скриптов. За инструкциями обратитесь к странице Propose a Cherry Pick.

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

Когда в вашем пулреквесте есть определённый коммит, который нужно применить в ветке release-1.9, вам нужно запустить перечисленные ниже скрипты в этой вете из вашего локального окружения.

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Теперь зафиксируйте изменения в вашем пулреквесте с применённым коммитом, теперь там будет сгенерированная спецификация OpenAPI и связанные с ней файлы. Отслеживайте этот пулреквест до тех пор, пока он не будет объединен в ветке release-1.9.

Сейчас у вас и в ветке master, и в ветке release-1.9 есть обновленный файл types.go вместе с множеством сгенерированных файлов, в которых отражаются изменения, внесенные вами в types.go. Обратите внимание, что сгенерированная спецификация OpenAPI и другие сгенерированные файлы в ветке release-1.9 не обязательно совпадают с сгенерированными файлами в ветке master. Сгенерированные файлы в ветке release-1.9 содержат элементы API только из Kubernetes 1.9. Сгенерированные файлы в ветке master могут содержать элементы API не только для версии 1.9, но и для 1.10, которая ещё находится в разработке.

Генерация справочной документации

В предыдущем разделе было показано, как отредактировать исходный файл, а затем сгенерировать несколько файлов, включая api/openapi-spec/swagger.json в репозитории kubernetes/kubernetes. Файл swagger.json — это файл определения OpenAPI, который используется для генерации справочной документации API.

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

Что дальше

• Генерация справочной документации для API Kubernetes
• Генерация справочной документации для компонентов и инструментов Kubernetes
• Генерация справочной документации для команд kubectl

5.2 - Руководство по быстрому старту

На этой странице показано, как использовать скрипт update-imported-docs для генерации справочной документации Kubernetes. Скрипт автоматизирует настройку сборки и генерирует справочную документацию для выпуска.

Подготовка к работе

Требования:

• Наличие компьютера под управлением ОС Linux или macOS.

• Установленные следующие инструменты:

  • Python версии 3.7.x
  • Git
  • Golang версии 1.13+
  • Pip, который потребуется для установки PyYAML
  • PyYAML версии 5.1.2
  • make
  • gcc compiler/linker
  • Docker (требуется только для справочника команды kubectl)

• В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

• Вам нужно знать, как создать пулреквест в репозитории на GitHub. Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел Работа из локальной копии.

Получение репозитория документации

Убедитесь, что ваша копия репозитория website обновлена в соответствии с оригинальным репозиторием kubernetes/website, а затем склонируйте вашу копию website.

mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git

Определите базовую директорию вашей копии. Например, при выполнении предыдущего блока команд, то базовой директорией будет website. Далее в этом руководстве базовая директория в командах будет обозначаться <web-base>.

Заметка: Если вы хотите изменить контент инструментов компонента и справочник API, посмотрите руководство по участию в оригинальной документации.

Краткий обзор update-imported-docs

Скрипт update-imported-docs находится в директории <web-base>/update-imported-docs/.

Этот скрипт генерирует следующие справочники:

• Справочные страницы для компонентов и инструментов
• Справочник команды kubectl
• API-справочник Kubernetes

Скрипт update-imported-docs генерирует справочную документацию Kubernetes из исходного кода Kubernetes. Скрипт создает временную директорию /tmp на вашем компьютере и клонирует необходимые репозитории в эту директорию: kubernetes/kubernetes и kubernetes-sigs/reference-docs. Скрипт добавляет путь временной директории в переменную окружения GOPATH. Кроме этого определяются три дополнительные переменные среды:

• K8S_RELEASE
• K8S_ROOT
• K8S_WEBROOT

Для успешного выполнения скрипта нужно передать два аргумента:

• Конфигурационный файл в формате YAML (reference.yml)
• Версия выпуска, например, 1.17

Конфигурационный файл содержит поле generate-command. Поле generate-command определяет ряд инструкций для сборки из kubernetes-sigs/reference-docs/Makefile. Переменная K8S_RELEASE определяет версию выпуска.

Скрипт update-imported-docs выполняет следующие шаги:

1. Клонирует репозитории, указанные в конфигурационном файле. Для генерации справочной документации клонируемым репозиторием по умолчанию является kubernetes-sigs/reference-docs.
2. Запускает команды в клонированных репозиториях для подготовки генератора документации, а затем генерирует файлы HTML и Markdown.
3. Копирует сгенерированные файлы HTML и Markdown в локальную копию репозитория <web-base> в директории, указанные в конфигурационном файле.
4. Обновляет ссылки на команды kubectl из kubectl.md, ссылаясь на разделы в справочнике по команде kubectl. . Когда сгенерированные файлы находятся в вашем локальной копии репозитория <web-base>, вы можете отправить их в виде пулреквеста в оригинальный репозиторий <web-base>.

Формат конфигурационного файла

Каждый конфигурационный файл может содержать несколько репозиториев, которые будут импортированы вместе. При необходимости вы можете вручную изменить конфигурационный файл. Вы можете создавать новые конфигурационные файлы для импорта других групп документации. Ниже приведен пример файла конфигурации в формате YAML:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Каждый Markdown-файл документации, импортированный инструментом, должен соответствовать руководству по оформлению документации.

Настройка reference.yml

Откройте файл <web-base>/update-imported-docs/reference.yml для редактирования. Не изменяйте значение в поле generate-command, если не понимаете, как эта команда используется для сборки справочников. Вам нет необходимости править файл reference.yml. В некоторых случаях изменения в исходном коде основного репозитория могут потребовать внесения изменений в конфигурационный файл (например, зависимости версий golang и изменения сторонних библиотек). Если у вас возникли проблемы со сборкой, обратитесь за помощью к команде SIG-Docs на канале #sig-docs в Slack Kubernetes.

Заметка: Команда generate-command является необязательной, её можно использовать для выполнения указанной команды или небольшого скрипта, чтобы сгенерировать документацию из репозитория.

В файле reference.yml секция files содержат список полей src и dst. В поле src хранится путь к сгенерированному Markdown-файлу в клонированной директории сборки kubernetes-sigs/reference-docs, а поле dst определяет, куда скопировать этот файл в клонированном репозитории kubernetes/website. Например:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Обратите внимание, что в случае наличия множества файлов, которые нужно скопировать из одной директории в другую, то для это можете воспользоваться подстановочными знаки в поле src. Вам нужно указать имя директории в поле dst. Например:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Запуск инструмента update-imported-docs

Вы можете запустить инструмент update-imported-docs следующим образом:

cd <web-base>/update-imported-docs
./update-imported-docs <configuration-file.yml> <release-version>

Например:

./update-imported-docs reference.yml 1.17

Исправление ссылок

Конфигурационный файл release.yml содержит инструкции по исправлению относительных ссылок Для исправления относительных ссылок в импортированных файлах, установите для свойство gen-absolute-links в значение true. В качестве примера можете посмотреть файл release.yml.

Внесение изменений в kubernetes/website

Список сгенерированных и скопированных файлов в <web-base> можно узнать, как показано ниже:

cd <web-base>
git status

В выводе команды будут показаны новые и измененные файлы. Полученный вывод может отличаться в зависимости от изменений основного исходного кода.

Сгенерированные файлы инструментом

content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

Сгенерированные справочные файлы для команды kubectl

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/css/font-awesome.min.css

Сгенерированные файлы и директории для справочника API Kubernetes

static/docs/reference/generated/kubernetes-api/v1.17/index.html
static/docs/reference/generated/kubernetes-api/v1.17/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.17/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.17/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.17/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.17/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff2

Выполните git add и git commit, чтобы зафиксировать файлы в репозитории.

Создание пулреквеста

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят.

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

Что дальше

Для генерации отдельной взятой справочной документации путём ручной настройки необходимых репозиториев сборки и выполнении скриптов сборки обратитесь к следующим руководствам:

• Генерация справочной документации для компонентов и инструментов Kubernetes
• Генерация справочной документации для команд kubectl
• Генерация справочной документации для API Kubernetes

5.3 - Генерация справочной документации для API Kubernetes

На этой странице рассказывается про обновление справочной документации по API Kubernetes.

Справочная документация по API Kubernetes собирается из спецификации OpenAPI Kubernetes с использованием инструмента генерации kubernetes-sigs/reference-docs.

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

Продолжайте чтение данной странице, если вы хотите перегенерировать справочную документацию из спецификации OpenAPI.

Подготовка к работе

Требования:

• Наличие компьютера под управлением ОС Linux или macOS.

• Установленные следующие инструменты:

  • Python версии 3.7.x
  • Git
  • Golang версии 1.13+
  • Pip, который потребуется для установки PyYAML
  • PyYAML версии 5.1.2
  • make
  • gcc compiler/linker
  • Docker (требуется только для справочника команды kubectl)

• В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

• Вам нужно знать, как создать пулреквест в репозитории на GitHub. Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел Работа из локальной копии.

Настройка локальных репозиториев

Создайте рабочую область и определите переменную окружения GOPATH.

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Загрузите локальные копии следующих репозиториев:

go get -u github.com/kubernetes-sigs/reference-docs

go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec

Если у вас ещё нет копии репозитория kubernetes/website, клонируйте её на свой компьютер:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

• Определите базовую директорию вашей копии репозитория kubernetes/kubernetes. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/k8s.io/kubernetes. В остальных командах базовая директория будет именоваться как <k8s-base>.

• Определите базовую директорию вашей копии репозитория kubernetes/website. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/<your-username>/website. В остальных командах базовая директория будет именоваться как <web-base>.

• Определите базовую директорию вашей копии репозитория kubernetes-sigs/reference-docs. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/kubernetes-sigs/reference-docs. В остальных командах базовая директория будет именоваться как <rdocs-base>.

Генерация справочной документации API

Далее в этом разделе рассматривается генерация справочной документации по API Kubernetes.

Настройка переменных для сборки

• K8S_ROOT со значением <k8s-base>.
• WEB_ROOT со значением <web-base>.
• K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения K8S_RELEASE со значением 1.17.

Примеры:

export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17

Создание версионированной директории и получение Open API spec

Скрипт сборки updateapispec создает версионированную директорию для сборки. После создания директории спецификация Open API генерируется из репозитория <k8s-base>. Таким образом версия конфигурационных файлов и спецификация Kubernetes Open API будут совпадать с версией выпуска. Имя версионированной директории имеет следующий вид: v<major>_<minor>.

В директории <rdocs-base> выполните следующий скрипт сборки:

cd <rdocs-base>
make updateapispec

Сборка справочной документации API

Скрипт сборки copyapi создает справочник API и копирует генерированные файлы в каталоги в <web-base>. Выполните следующую команду в <rdocs-base>:

cd <rdocs-base>
make copyapi

Убедитесь в том, что перечисленные ниже два файлы были сгенерированы:

[ -e "<rdocs-base>/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Перейдите в корень директории <web-base> и посмотрите, какие файлы были изменены:

cd <web-base>
git status

Вывод команды будет примерно следующим:

static/docs/reference/generated/kubernetes-api/v1.17/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.17/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.17/index.html
static/docs/reference/generated/kubernetes-api/v1.17/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.17/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.17/js/scroll.js

Обновление указателя API-справочника

При генерации справочной документации для нового выпуска в файле <web-base>/content/en/docs/reference/kubernetes-api/api-index.md нужно прописать номер предстоящей версии.

• Откройте файл <web-base>/content/en/docs/reference/kubernetes-api/api-index.md и обновите номер версии справочника API. Например:

  ---
  title: v1.17
  ---
  
  [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
  

• Откройте файл <web-base>/content/en/docs/reference/_index.md и добавьте ссылку на последний справочник API. Удалите самую старую версию справочника API. В этом файле должно быть 5 ссылок на новейшие API-справочники.

Тестирование справочника API локально

Соберите обновлённую версию API-справочника на своём компьютере. Проверьте ваши изменения на локальной предварительной версии сайта.

cd <web-base>
make docker-serve

Фиксация изменений

В директории <web-base> выполните команду git add и git commit для фиксации изменений в репозитории.

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте свой пулреквест и при необходимости отвечайте на комментарии. Не забывайте отслеживать активность в собственном пулреквесте до тех пор, пока он не будет принят.

Отправьте свои изменения в виде пулреквеста в репозиторий kubernetes/kubernetes. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

Что дальше

• Руководство по быстрому старту генерации справочной документации
• Генерация справочной документации для компонентов и инструментов Kubernetes
• Генерация справочной документации для команд kubectl

5.4 - Генерация справочной документации для команд kubectl

На этой странице показано, как сгенерировать справочник для команды kubectl.

Заметка: На этой странице показывается, как сгенерировать справочную документацию для таких команд kubectl, как kubectl apply и kubectl taint. Этот раздел не рассматривает генерацию справочной страницы для опций kubectl. Инструкции по генерации справочной страницы опций kubectl смотрите в разделе Генерация справочной документации для компонентов и инструментов Kubernetes.

Подготовка к работе

Требования:

• Наличие компьютера под управлением ОС Linux или macOS.

• Установленные следующие инструменты:

  • Python версии 3.7.x
  • Git
  • Golang версии 1.13+
  • Pip, который потребуется для установки PyYAML
  • PyYAML версии 5.1.2
  • make
  • gcc compiler/linker
  • Docker (требуется только для справочника команды kubectl)

• В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

• Вам нужно знать, как создать пулреквест в репозитории на GitHub. Для этого нужно создание собственной копии репозитория. Для получения дополнительной информации смотрите раздел Работа из локальной копии.

Настройка локальных репозиториев

Создайте рабочую область и определите переменную окружения GOPATH.

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Загрузите локальные копии следующих репозиториев:

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u kubernetes-sigs/reference-docs

Если у вас ещё нет копии репозитория kubernetes/website, клонируйте её на свой компьютер:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

Удалите пакет spf13 в $GOPATH/src/k8s.io/kubernetes/vendor/github.com.

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

В репозитории kubernetes/kubernetes использует исходный код kubectl и kustomize.

• Определите базовую директорию вашей копии репозитория kubernetes/kubernetes. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/k8s.io/kubernetes. В остальных командах базовая директория будет именоваться как <k8s-base>.

• Определите базовую директорию вашей копии репозитория kubernetes/website. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/<your-username>/website. В остальных команд базовая директория будет именоваться как <web-base>.

• Определите базовую директорию вашей копии репозитория kubernetes-sigs/reference-docs. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/kubernetes-sigs/reference-docs. В остальных команд базовая директория будет именоваться как <rdocs-base>.

В вашем локальном репозитории k8s.io/kubernetes переключитесь в нужную вам ветку и убедитесь, что она в актуальном состоянии. Например, если вам нужно сгенерировать документацию для Kubernetes 1.17, вы можете использовать эти команды:

cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0

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

Редактирование исходного кода kubectl

Справочная документация по команде kubectl генерируется автоматически из исходного кода kubectl. Если вы хотите изменить справочную документацию, сначала измените один или несколько комментариев в исходном коде kubectl. Сделайте изменения в локальный репозиторий kubernetes/kubernetes, а затем отправьте пулреквест в ветку master репозитория github.com/kubernetes/kubernetes.

PR 56673 — пример пулреквеста, который исправляет опечатку в исходном коде kubectl.

Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят в ветку master репозитория kubernetes/kubernetes.

Применение вашего изменения в ветку выпуска

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

Например, предположим, что ветка master используется для разработки Kubernetes 1.10, а вам нужно бэкпортировать ваше изменение в ветку release-1.15. За инструкциями обратитесь к странице Propose a Cherry Pick.

Отслеживайте ваш пулреквест с применённым изменением до тех пор, пока он не будет объединён в ветку выпуска.

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

Настройка переменных для сборки

Перейдите на <rdocs-base>. В командной строке установите следующие переменные окружения.

• K8S_ROOT со значением <k8s-base>.
• WEB_ROOT со значением <web-base>.
• K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения K8S_RELEASE со значением 1.17.

Примеры:

export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17

Создание версионированной директории

Скрипт сборки createversiondirs создаёт версионированную директорию и копирует туда конфигурационные файлы справочника kubectl. Имя версионированной директории имеет следующий вид: v<major>_<minor>.

В директории <rdocs-base> выполнение следующий скрипт сборки:

cd <rdocs-base>
make createversiondirs

Переход в тег выпуска в k8s.io/kubernetes

В вашем локальном репозитории <k8s-base> перейдите в ветку с версией Kubernetes, для которой вы хотите получить документацию. Например, если вы хотите сгенерировать документацию для Kubernetes 1.17, перейдите в тег v1.17.0. Убедитесь, что ваша локальная ветка содержит актуальные изменения.

cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0

Выполнение кода для генерации документации

В вашей локальной директории <rdocs-base> запустите скрипт сборки copycli. Команда выполняется от пользователя root:

cd <rdocs-base>
make copycli

Команда copycli удаляет временную директорию сборки, генерирует файлы команды kubectl и копирует полученную HTML-страницу справочника команде kubectl и ресурсы в <web-base>.

Проверка сгенерированных файлов

Убедитесь в том, что перечисленные ниже два файлы были сгенерированы:

[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Проверка скопированных файлов

Убедитесь в том, все сгенерированные файлы были скопированы в вашу директорию <web-base>:

cd <web-base>
git status

В выводе должны перечислены изменённые файлы:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

Также в выводе должно быть:

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

Проверка документации локально

Соберите документацию Kubernetes в вашей директории <web-base>.

cd <web-base>
make docker-serve

Посмотрите локальную предварительную версию сайта.

Добавление и фиксация изменений в kubernetes/website

Выполните команду git add и git commit для фиксации файлов.

Создание пулреквеста

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

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

Что дальше

• Руководство по быстрому старту генерации справочной документации
• Генерация справочной документации для компонентов и инструментов Kubernetes
• Генерация справочной документации для API Kubernetes

5.5 - Генерация справочных страниц для компонентов и инструментов Kubernetes

На этой странице показывается, как собирать справочные страницы компонентов и инструментов Kubernetes.

Подготовка к работе

Начните с раздела с требованиями в руководстве по быстрому старту.

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

Что дальше

• Краткое руководство по генерации справочной документации
• Генерация справочной документации для команд kubectl
• Генерация справочной документации для API Kubernetes
• Участие в документации основного кода проекта Kubernetes

6 - Локализация документации Kubernetes

На этой странице рассказывается, как локализовать документацию на разные языки.

Начало работы

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

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

Определение двухбуквенного кода языка

Первым делом ознакомьтесь со стандартом ISO 639-1, чтобы найти двухбуквенный код страны для вашей локализации. Например, двухбуквенный код для корейского языка будет ko.

Создание копии репозитория

Для начала создайте собственную копию репозитория оригинального репозитория kubernetes/website.

Затем клонируйте свою копию репозитория и перейдите в неё с помощью команды cd:

git clone https://github.com/<username>/website
cd website

Создание пулреквеста

Далее откройте пулреквест (PR) с локализацией в репозиторий kubernetes/website.

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

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

Вступление в GitHub-организацию Kubernetes

Как только, как вы открыли PR с локализацией, вы можете стать членом организации Kubernetes на GitHub. Каждый член команды должен подать запрос на членство в организации в репозитории kubernetes/org.

Добавление команды локализации на GitHub

Теперь нужно добавить вашу команду локализации Kubernetes в файл sig-docs/teams.yaml. Для примера добавления команды локализации можете посмотреть PR, добавляющий испанскую команду локализации.

Члены @kubernetes/sig-docs-**-owners — могут одобрять PR, которые изменяют файлы внутри (и только там) директории с локализацией: /content/**/.

Для каждой локализации группа @kubernetes/sig-docs-**-reviews служит для автоматизации выбора проверяющих новых PR.

Члены @kubernetes/website-maintainers могут создавать новые ветки для координации работ по переводу.

Члены @kubernetes/website-milestone-maintainers могут использовать Prow-команду /milestone для контрольных точек для ишью или PR.

Настройка рабочего процесса

Затем добавьте собственную GitHub-метку для вашей локализации в репозиторий kubernetes/test-infra. Метка позволяет фильтровать ишью и пулреквесты по конкретному языку.

Смотрите пример добавления метки для итальянского языка.

Поиск сообщества

Сообщите участниками группы Kubernetes SIG Docs о вашем намерении перевода документации! Подключайтесь к Slack-каналу SIG Docs. Остальные команды по локализации с радостью помогут вам начать и ответят на любые вопросы.

Вы также можете создать Slack-канал для своей локализации в репозитории kubernetes/community. Для примера посмотрите PR с добавлением Slack-канала для индонезийского и португальского языков.

Необходимый минимум контента

Изменение конфигурации сайта

Сайт Kubernetes использует использует фреймворк Hugo. Конфигурация сайта у Hugo находится в файле config.toml. Для поддержки новой локализации вам нужно отредактировать файл config.toml.

Добавьте блок с конфигурацией для нового языка в config.toml после существующего блока [languages]. Например, конфигурация для немецкой локализации будет выглядить так:

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3

При выбора значения для параметра weight в блока найдите языковой блок с наибольшим значением и прибавьте к нему 1.

Для получения дополнительной информации о многоязычной поддержке в Hugo посмотрите страницу "Multilingual Mode".

Добавление директории для локализации

Добавьте директорию для вашего языка в директорию content репозитория. Например, двухбуквенный код для немецкого будет de:

mkdir content/de

Перевод норм поведения сообщества

Откройте PR в репозитории cncf/foundation и добавьте перевод норм поведения на своём языке.

Добавление перевода для файла README

Чтобы помочь другим участников локализации добавьте новый файл README-**.md в корневую директорию k/website, где ** означает двухбуквенный код языка. Например, немецкий файл README будет именоваться как README-de.md.

Подготовьте рекомендации для участников в файле для конкретной локализации README-**.md. В этом файле должна быть точно такая же информация, что и в оригинальном README.md ту же информацию, включая также:

• Контактное лицо проекта локализации
• Любая другая информация, относящаяся к локализации

После создания перевода файла README добавьте ссылку на файл в основной английский файл README.md и добавьте контактную информацию на английском языке. Вы можете указать логин на GitHub, адрес электронной почты, Slack-канал или какой-нибудь способ связи. Вам также нужно добавить ссылку на перевод норм поведения в сообществе.

Настройка файлов OWNERS

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

• reviewers: список Kubernetes-команд с ролями рецензентов, в данном случае команда sig-docs-**-reviews будет создана в разделе Добавление команды локализации на GitHub.
• approvers: список Kubernetes-команд с ролями утверждающих, в данном случае команда sig-docs-**-owners будет создана в разделе Добавление команды локализации на GitHub.
• labels: список GitHub-меток, которые будут автоматически добавляться к PR, в данном случае метка языка будет создана в разделе Настройка рабочего процесса.

Дополнительную информацию о файле OWNERS вы можете получить по ссылке go.k8s.io/owners.

Испанский файл OWNERS с кодом языка es выглядит следующим образом:

# See the OWNERS docs at https://go.k8s.io/owners

# This is the localization project for Spanish.
# Teams and members are visible at https://github.com/orgs/kubernetes/teams.

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- language/es

После добавления файла OWNERS в определенном языке нужно обновить корневой файл OWNERS_ALIASES, добавив новые команды локализации Kubernetes — sig-docs-**-owners и sig-docs-**-reviews.

Для каждой команды добавьте список GitHub-пользователей из раздела Добавление команды локализации на GitHub, перечислите их в алфавитном порядке.

--- a/OWNERS_ALIASES
+++ b/OWNERS_ALIASES
@@ -48,6 +48,14 @@ aliases:
     - stewart-yu
     - xiangpengzhao
     - zhangxiaoyu-zidif
+  sig-docs-es-owners: # Admins for Spanish content
+    - alexbrand
+    - raelga
+  sig-docs-es-reviews: # PR reviews for Spanish content
+    - alexbrand
+    - electrocucaracha
+    - glo-pena
+    - raelga
   sig-docs-fr-owners: # Admins for French content
     - perriea
     - remyleone

Перевод контента

Локализация всей документации Kubernetes — колоссальная задача. Вполне нормально начать переводить что-то небольшое, а затем со временем делать перевод больших страниц.

Как минимум, все локализации должны включать:

Переведенные файлы должны находиться в собственной директории content/**/, но в во всём остальном должны быть такие, как и оригинал на английском. Например, чтобы подготовить Основы Kubernetes для перевода на немецкий язык, создайте поддиректорию в директории content/de/ и скопируйте туда оригинальный английский файл:

mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md

С помощью соответствующих инструментов можно ускорить процесс перевода. Например, у некоторых редакторов есть плагины для быстрого перевода текста.

Внимание: Использование только машинного перевода не будет соответствовать минимальному уровню качества и поэтому такой перевод требует тщательного ручного рассмотрения для соблюдения стандарта качества.

To ensure accuracy in grammar and meaning, members of your localization team should carefully review all machine-generated translations before publishing.

Исходные файлы

Локализация должна исходить из самой последней версии оригинальной документации — v1.24.

Для того, чтобы получить исходные файлы последней версии:

1. Перейдите в репозиторий сайта Kubernetes по адресу https://github.com/kubernetes/website.
2. Выберите ветку release-1.X самой последней версии.

Текущая последняя версия v1.24, поэтому веткой для этого релиза будет release-1.24.

Сообщения на сайте в i18n/

Локализации должны включать содержимое файла i18n/en.toml в новый языковой файл. В качестве примера рассмотрим немецкую локализацию: i18n/de.toml.

Добавьте новый файл локализации в i18n/. Например, для немецкой локализации (de):

cp i18n/en.toml i18n/de.toml

Затем переведите значение каждого сообщения:

[docs_label_i_am]
other = "ICH BIN..."

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

Глоссарий и руководство по оформления для языка

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

Стратегия работы с ветками

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

Совместная работа в рабочих ветках может быть организована следующим образом:

1. Член команды @kubernetes/website-maintainers создает ветку из оригинальной ветки на https://github.com/kubernetes/website.

   После того, как вы добавите свою команду локализации в репозиторий kubernetes/org, ваши утверждающие из группы будет присоединены к команде @kubernetes/website-maintainers.

   Мы рекомендуем следующую схему именования веток:

   dev-<оригинальная версия>-<код языка>.<контрольная точка команды>

   Например, утверждающий в немецкой группе локализации открывает рабочую ветку dev-1.12-de.1 непосредственно в репозитории kubernetes/website из ветки для Kubernetes v1.12.

2. Остальные участники создают новые ветки с изменениями на основе рабочей ветки.

   Например, участник немецкой группы локализации открывает пулреквест с изменениями в kubernetes:dev-1.12-de.1 из username:local-branch-name.

3. Утверждающий проверяет изменения и объединяют ветки в рабочую веткой.

4. Периодически утверждающий объединяет рабочую ветку в оригинальную ветку, открывая и принимая новый пулреквест. Не забудьте объединить (squash) коммиты перед слиянием пулреквеста.

Повторяйте шаги 1-4 до тех пор, пока не будет завершена локализация. Например, по мере работы над немецким переводом, рабочие ветки будут меняться: dev-1.12-de.2, dev-1.12-de.3 и т.д.

Команды должны объединять переведённый контент в ту же ветку выпуска, из которой она была создана. Например, рабочая ветка, созданная из версии release-1.24, должна сливаться с веткой версии 1.17.

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

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

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

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

Участие в работе над оригинальным контентом

SIG Docs приветствует участие и дополнения в английскую документацию.

Помощь для существующей локализации

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

Что дальше

Как только локализация будет соответствовать требованиям установленного рабочего процесса и содержать требуемый минимум контента, группа SIG Docs:

• Добавит язык на сайт
• Сообщит о новой локализации на каналах Cloud Native Computing Foundation (CNCF), включая блог Kubernetes.

7 - Участие в SIG Docs

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

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

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

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

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

Любой

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

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

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

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

Рецензенты

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

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

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

Процесс выбора рецензентов для проверки пулреквестов автоматизирован. Вы можете попросить проверку у определенного рецензента, написав комментарий в пулреквесте: /assign [@_github_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 добавить вас в GitHub-группу @kubernetes/sig-docs-pr-reviews. Только члены GitHub-группы kubernetes-website-admins могут добавлять новых членов в какую-либо другую группу.

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

Утверждающие — члены GitHub-группы @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 добавить вас в GitHub-группу@kubernetes/sig-docs-maintainers. Только члены GitHub-группы 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 основывается на двух разных механизмах: группы GitHub и файлы OWNERS.

GitHub-группы

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

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

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

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

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

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

• blunderbuss
• approve

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

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

Кроме того, в каждом 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 или председателя SIG Docs.

Что дальше

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

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