Вклад в knative/docs

• Перед тем как начать
• Вклад в документацию
• Роли участников документации

Сперва спасибо за то, что уделяете время для вклада!

Ниже приведены руководства по вкладу в документацию проекта Knative. Это всего лишь рекомендации, а не правила. Используйте свое лучшее суждение, и не бойтесь предлагать изменения в этом документе через pull request.

Перед тем как начать

Код поведения

Проект Knative следует Коду поведения Knative. Участвуя, вы обязаны придерживаться этого кода. Пожалуйста, сообщайте о недопустимом поведении на knative-code-of-conduct@googlegroups.com.

Лицензионные соглашения

Мы будем рады принять ваш вклад! Но прежде чем мы сможем его принять, вам нужно заполнить Google CLA. Важно: Вы должны заполнить CLA с тем же адресом электронной почты, который вы использовали для создания вашего аккаунта на GitHub.

После того как вы заполните CLA, мы сможем принимать ваши pull requests. Это необходимо потому, что вы являетесь владельцем авторских прав на свои изменения, даже после того, как ваш вклад стал частью этого проекта. Поэтому этот договор просто позволяет нам использовать и распространять ваши вклады как часть проекта.Примечание: Ваши вклады проверяются с помощью адреса электронной почты, которым вы подписываете CLA. Поэтому установление вашего аккаунта на GitHub на приватный режим не поддерживается, так как все коммиты из приватных аккаунтов отправляются с адреса noreply.

Гайдлайн стиля

Документация проекта Knative следует Google Developer Documentation Style Guide. Используйте это как справочник для вопросов стиля написания. Используйте это как справочник для вопросов стиля написания.

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

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

1. Проверьте список issues для документации Knative перед созданием нового issue, чтобы избежать дублирования.
2. Используйте правильный шаблон при создании своего issue. Доступны два шаблона:
   • Жалоба на ошибку: Если вы сообщаете об ошибке в существующей документации, используйте этот шаблон. Это может быть что угодно от поломанных примеров до опечаток. При создании жалобы на ошибку предоставьте как можно больше деталей и предложите возможные исправления проблемы. Если вы знаете, какой компонент Knative связан с вашей ошибкой, вы можете назначить соответствующего лидера рабочей группы.
   • Запрос на новую функцию: Для предстоящих изменений в документации или запросов информации по конкретной теме. Примечание: проблемы с кодом должны быть открыты против индивидуальных репозиториев Knative, в то время как проблемы с документацией следует отправлять в репозиторий knative/docs. Если проблема связана с сайтом https://knative.dev, откройте её в репозитории knative/website.### Группа работы

Группа документации Knative встречается каждые две недели по вторникам в 9:30 утра по тихоокеанскому времени. Нажмите здесь, чтобы увидеть конкретные даты в календаре групп работы Knative.

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

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

Существует несколько способов начала сотрудничества в документации Knative:

• Поищите задачу, подходящую для новичков, в списке открытых задач.

• Протестируйте Knative и отправьте нам обратную связь. Например, пройдите через руководства по установке и затем попробуйте Начало работы с Knative Serving или Начало работы с Eventing.

  Вы должны поддерживать журнал трений вашего опыта и использовать его для открытия вашей первой серии запросов на слияние. Примеры:

  • Что было трудным для вас?
  • Были ли вы запутаны чем-то потому что шаги были непонятны?
  • Был ли упомянута какая-либо зависимость?Несколько указаний и других соображений

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

• Есть ли несколько мест, где можно исправить эту проблему?

  • Есть ли другие страницы, на которых следует применять ваши изменения?

  • Не помогло бы наличие ссылки на больше или связанную информацию на странице? На связанной странице? - Был ли заголовок или описание вводящими в заблуждение? Ожидали ли вы найти что-то другое в этом разделе документации?

• Если вы нашли проблему и у вас нет времени открыть pull request, сообщите нам о проблеме и откройте issue.

Отправка pull requests для документации — что можно ожидать

Вот что обычно происходит, когда вы открываете pull request против репозитория knative/docs:1. Один из назначенных поддерживаемым репозиторием администраторов будет сортировать pull request, назначая относительный приоритет, добавляя подходящие метки и выполняя начальную проверку документации.

1. Если pull request включает значительные технические изменения, такие как новые функции или новые и измененные образцы кода, pull request будет передан специалисту по предметной области (SME), обычно это инженер, работающий над Knative, для технического рассмотрения и одобрения.

2. Когда как технический писатель, так и специалисты по предметной области удовлетворены качеством текста и технической точностью содержания, pull request может быть объединён. Pull request требует двух меток до того, как его можно будет объединить: lgtm и approved. - Специалист по предметной области отвечает за проверку технической точности и добавление метки lgtm.

   • Технические писатели Knative добавляют метку approved, когда содержание соответствует стандартам качества, ясности и организации (см. Руководство по стилю).

Мы ценим ваши вклады в документацию, поэтому если вы открываете pull request, мы поможем вам объединиться. Вы также можете опубликовать в канале #docs Slack, чтобы получить отзывы по вашим идеям или найти области для участия перед созданием pull request.

Размещение ваших документов в правильном месте

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

Выбор правильного репозитория

В зависимости от типа контента, который вы хотите внести, он может находиться в одном из репозиториев кода Knative (knative/serving, knative/eventing, и т.д.) или в репозитории документации knative/docs.- Контент, ориентированный на участников проекта

• Документация: Включает содержание, которое является компоненто-специфичным и относится только к вкладчикам данного компонента. Документация, ориентированная на вкладчиков, находится в соответствующей папке docs репозитория этого компонента. Например, если вы делаете вклад в код компонента Knative Serving, вам может потребоваться добавить информацию, ориентированную на вкладчиков, в папку docs репозитория knative/serving.

• Примеры кода: Включает в себя код или примеры, связанные с участниками проекта. Код или примеры, ориентированные на участников, также должны находиться в соответствующих репозиториях компонентов. Например, специфический тестовый код для Eventing находится в папке knative/eventing tests.- Пользовательский ориентированный контент

• Документация: Включает все материалы для пользователей Knative. Внешняя документация, предназначенная для пользователей, должна находиться в репозитории knative/docs. Все содержимое в knative/docs публикуется на https://knative.dev.

• Примеры кода: Включает примеры кода для пользователей и сопутствующие им пошаговые инструкции. Примеры кода для пользователей в настоящее время разделены на две различные локации внутри репозитория knative/docs. Подробнее см. следующий раздел о том, как определить место добавления вашего примера кода.

Определение места добавления примеров кода, ориентированных на пользователя

Существует два типа примеров кода, ориентированных на пользователя: владение и поддержка Knative и владение и поддержка сообщества.

• Владение и поддержка Knative: Включает примеры кода, активно поддерживающиеся и прошедшие проверку на соответствие требованиям. Чтобы обеспечить актуальность контента и балансировать доступные ресурсы, только те примеры кода, которые соответствуют следующим требованиям, расположены в папках docs/[*component*]/samples репозитория knative/docs: - Активно поддерживаются — У примера кода есть активный член команды Knative, который обязуется регулярной поддержкой этого контента и гарантирует его актуальность и работоспособность для каждого выпуска продукта.

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

  • Проходят проверку на соответствие требованиям — Все примеры кода в папках docs/[компонент]/samples должны соответствовать (и проходить) проверку на соответствие требованиям e2e тесты. В зависимости от того, какой компонент Knative охватывает ваш пример кода, ваш запрос на внесение изменений должен добавить этот пример в одной из следующих папок:

  • Примеры использования Eventing: /docs/eventing/samples

  • Примеры использования Serving: /docs/serving/samples

• Образцы, управляемые сообществом: Кодовые образцы, предоставленные участниками проекта Knative. Эти образцы могут не получать регулярное обслуживание. Возможно, что некоторые образцы больше не актуальны и не поддерживаются автором. Хотя мы поощряем участников поддерживать свои материалы, мы признаем, что это не всегда возможно по различным причинам, таким как другие обязательства и ограничение времени.

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

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

Вероятнее всего, ваш вклад в документацию либо связан с новыми или изменёнными функциями продукта, либо является исправлением или обновлением существующего контента.- Новые или изменённые функции: Если вы добавляете или обновляете документацию для новых или изменённых функций, вероятно, вам следует открыть ваш запрос на внесение изменений (pull request) против ветки master. Все предварительные выпуски активного развития Knative должны находиться в master.

• Исправления и обновления: Если вы нашли проблему в прошлом выпуске, например опечатку или устаревший контент, вам, скорее всего, потребуется открыть несколько последовательных запросов на внесение изменений (pull requests). Если это не последующий pull request, хотя бы добавьте метки "cherrypick" к вашему первоначальному pull request, чтобы указать, в каких из прошлых выпусков ваши изменения затрагивают.

  Например, если вы нашли опечатку на странице выпуска v0.5, то эта страница в ветке master также, вероятно, будет содержать эту опечатку. Чтобы исправить опечатку:

  1. Откройте запрос на слияние (PR) против ветки
     master.
  2. Добавьте одну или несколько меток cherrypick-#.# к этому PR, чтобы указать,
     какие из прошлых веток выпуска также следует исправить. В общем случае, мы поддерживаем только самую последнюю нумерованную версию.
  3. Если вы хотите самостоятельно завершить исправление (лучшая практика),
     откройте последующий PR, выполнив команду git cherry-pick [COMMIT#] против ветки release-0.5.
     Где [COMMIT#] — это коммит PR, который был объединён в master.
     Примечание: В зависимости от нагрузки и доступной пропускной способности один из членов команды Knative может помочь выполнить git cherry-pick, чтобы внести исправление в затронутую ветку выпуска(ей).См. список доступных версий документации на странице ветвей репозитория knative/docs.

Назначение владельцев и рецензентов

Для документов и примеров кода вам следует назначить ваш запрос на слияние (PR) одному владельцу ("Назначенному" / "Assignee") с помощью команды Prow /assign. Лучше всего установить "Назначенного" и включить других заинтересованных сторон как "Рецензентов", а не оставлять запрос на слияние незаполненным или позволять Prow автоматически назначать рецензентов.

Используйте команду /assign, чтобы установить владельца. Например: /assign @владелец_id

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

Если вы хотите уведомить и включить других заинтересованных сторон в процесс рецензирования вашего запроса на слияние, используйте команду /cc. Например: /cc @заинтересованная_сторона_id1 @заинтересованная_сторона_id2

Роли участников документацииПоскольку участие в создании документации требует другого набора навыков по сравнению с участием в работе над основой Knative, мы определили роли участников документации отдельно от ролей участников кода.Если вы ищете роли участников кода, см. раздел РОЛИ.

Член

Установленный участник работы над документацией Knative.

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

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

Требования

• Произвел несколько вкладов в проект или сообщество. Вклады могут включать, но не ограничиваются следующими пунктами:

  • Авторство и рецензирование запросов на слияние (PR) в репозиториях с документацией или сайтом на GitHub.

  • Создание и комментирование проблем на GitHub. - Вклад в обсуждение рабочих групп или сообществ.

• Подписан на knative-dev@googlegroups.com.

• Активно вносит вклад в одну или более областей.

• Получил одобрение от одного спонсора.

  • Выполняется путём добавления пользователя GitHub в организацию Knative.

Ответственности и привилегии

• Быстро реагирует на проблемы и запросы на слияние, назначенные ему.

• Активный владелец документов, которыми он внес вклад (за исключением случаев явной передачи права собственности).

  • Устраняет ошибки или проблемы в своих документах своевременно.

Как стать участником

Добавьте себя (отправив запрос на слияние) в список members в конфигурации Peribolos в репозитории knative/community (ссылка).

После того как вы будете добавлены в организацию Knative, откройте запрос на слияние для добавления себя как рецензента документов в файл OWNERS_ALIASES.Одобряющие документы способны как проверять, так и одобрять вклады в документацию. Хотя проверка документации сосредоточена на качестве написания и правильности, одобрение направлено на всестороннее принятие вклада, включающее долгосрочную поддерживаемость, соответствие руководящим принципам оформления, общую информационную архитектуру и удобство использования с точки зрения инженера. Одобряющие документы будут приглашать помощь инженеров для проверки вкладов с большим количеством кода в репозиторий с документацией.### Требования

• Рецензент репозитория с документацией минимум три месяца.

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

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

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

• Номинирован лидером области (с согласия других лидеров). - Выполнено через PR для обновления файла OWNERS.

Обязанности и привилегии

• Ответственный за контроль качества документации через рецензирование PR.

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

• Ожидается, что вы будете откликаться на запросы на рецензирование в соответствии с ожиданиями сообщества.

• Наставник участников и вкладчиков для улучшения их письма.

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

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

Как только вы почувствуете, что соответствуете критериям, вы можете попросить одного из текущих одобрителей представить вас как кандидата на должность одобрителя. Если все существующие одобрители согласны, что вы соответствуете критериям, откройте PR для добавления себя как docs-approver в файл OWNERS_ALIASES.