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

Если вы хотите поучаствовать в работе над документацией 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 общается следующими способами:

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

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

Примечание. Разработчики кода 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.32-ja.1.
  • Если вы пишете или обновляете документацию к выпуску грядущего изменения, то вам необходимо знать мажорную и минорную версию Kubernetes, в которой это изменение впервые появится.
    • Например, если переключатель возможностей (feature gates) JustAnExample должен измениться с альфа-версии на бета-версию в следующей минорной версии, вам необходимо знать номер этой версии.
    • Найдите ветку выпуска, названную для этой версии. Например, функциональность, которая изменились в выпуске vrelease-1.32, будет документирована в ветке dev-release-1.32.

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

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

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

  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, прочитайте расширенное руководство по участию в документации.

Изменено June 20, 2024 at 12:44 PM PST: Sync changest from andygol/k8s-website (36d05bc8a1)