From bc6cb17bb739b6203217f96103afc331e695fd73 Mon Sep 17 00:00:00 2001 From: Alexey Pyltsyn Date: Mon, 17 Feb 2020 18:47:29 +0300 Subject: [PATCH] Translate Start contributing page into Russian (#19124) --- content/ru/docs/contribute/start.md | 233 ++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 content/ru/docs/contribute/start.md diff --git a/content/ru/docs/contribute/start.md b/content/ru/docs/contribute/start.md new file mode 100644 index 0000000000..c6149d60a2 --- /dev/null +++ b/content/ru/docs/contribute/start.md @@ -0,0 +1,233 @@ +--- +title: Start contributing +slug: start +content_template: templates/concept +weight: 10 +card: + name: contribute + weight: 10 +--- + +{{% capture overview %}} + +Если вы хотите поучаствовать в работе над документацией Kubernetes, эта страница и связанные с ней темы могут помочь вам начать работу. Вам не нужно быть разработчиком или техническим писателем, чтобы внести вклад в документацию или улучшить сайт Kubernetes! Все, что вам нужно для тем на этой странице, это учетная запись на GitHub и браузер. + +Если вы ищете информацию про участие в репозиториях, связанным с кодом Kubernetes, обратитесь к [руководству сообщества Kubernetes](https://github.com/kubernetes/community/blob/master/governance.md). + +{{% /capture %}} + + +{{% capture body %}} + +## Основные сведения про документацию + +Документация Kubernetes написана на Markdown, обработана и развернута при помощи Hugo. Исходные файлы находятся на GitHub по адресу https://github.com/kubernetes/website. Основная часть документации хранится в директории `/content/en/docs/`. Часть справочной документации автоматически генерируется из скриптов в директории `update-imported-docs/`. + +Вы можете создавать новые задачи, редактировать содержимое и проверять изменения от других участников, — всё это доступно с сайта GitHub. Вы также можете использовать встроенный в GitHub поиск и историю коммитов. + +Не все задачи могут быть выполнены на GitHub, поэтому они обсуждаются в [intermediate](/docs/contribute/intermediate/) and +[advanced](/docs/contribute/advanced/) docs contribution guides. + +### Участие в документации SIG + +Документация Kubernetes поддерживается {{< glossary_tooltip text="специальной группой" term_id="sig" >}} (Special Interest Group, SIG) под названием SIG Docs. Мы [общаемся](#participate-in-sig-docs-discussions) с помощью канала Slack, списка рассылки и еженедельных видеозвонков. Будем рады новым участникам. Для получения дополнительной информации обратитесь к странице [Participating in SIG Docs](/docs/contribute/participating/). + +### Руководящие принципы по содержанию + +Сообщество SIG Docs разработало правила, которые касаются разрешенных видов контента в документации Kubernetes. Посмотрите [руководство по содержанию документации](/docs/contribute/style/content-guide/) для определения того, допустим ли контент, который вы хотите добавить. Задать вопросы про допустимый контент можно в Slack-канале [#sig-docs](#participate-in-sig-docs-discussions). + +### Правила оформления + +Мы поддерживаем [руководство по оформлению](/docs/contribute/style/style-guide/) с информацией о выборе, сделанном сообществом SIG Docs в отношении грамматики, синтаксиса, исходного форматирования и типографских соглашений. Прежде чем сделать свой первый вклад, просмотрите руководство по стилю и используйте его, когда у вас есть вопросы. + +SIG Docs совместными усилиями вносит изменения в руководство по оформлению. Чтобы предложить изменение или дополнение, добавьте его в повестку дня предстоящей встречи SIG Docs и посетите её, чтобы принять участие в обсуждении. Смотрите страницу с [продвинутым руководством](/docs/contribute/advanced/) для получения дополнительной информации. + +### Шаблоны страниц + +Мы используем шаблоны страниц, чтобы управлять представление наших страниц документации. Разберитесь как работают эти шаблоны, ознакомившись с разделом [Использование шаблонов страниц](/docs/contribute/style/page-templates/). + +### Макрокоды Hugo + +Документация Kubernetes с помощью Hugo конвертируется из формата разметки Markdown в HTML. Мы используем встроенные макрокоды Hugo, а также некоторые из своих собственных, созданных специально для документации Kubernetes. Посетите страницу [Нестандартные макрокоды Hugo](/docs/contribute/style/hugo-shortcodes/), чтобы узнать, как их использовать. + +### Мультиязычность + +Исходные файлы документации доступны на нескольких языках в директории `/content/`. Каждый язык имеет свою собственную директорию с двухбуквенным кодом, определенным стандартом[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php). Например, исходники документации для английского языка хранится в директории `/content/en/docs/`. + +Более подробную информацию про участие в работе над документацией на нескольких языках ["Localize content"](/docs/contribute/intermediate#localize-content) в промежуточном руководстве по добавлению. + +Если вы заинтересованы в переводе документации на новый язык, посмотрите раздел ["Локализация"](/docs/contribute/localization/). + +## Создание хороших заявок + +Любой, у кого есть аккаунт на GitHub, может создать заявку (issue, или отчет об ошибке) в документации Kubernetes. Если вы заметили какую-либо какую-либо ошибку, даже если вы не знаете, как её исправить, [откройте ишью](#how-to-file-an-issue). Но не делайте этого, если нашли небольшую ошибку, например, опечатку, которую вы при желании можете исправить самостоятельно. В этом случае можете [исправить ее](#improve-existing-content) вместо того, чтобы писать об этом. + +### Как создать заявку + +- **Для существующей страницы** + + Если заметили проблему на существующей странице в [документации Kubernetes](/docs/), перейдите в конец страницы и нажмите кнопку **Create an Issue**. Если вы ещё не авторизованы в GitHub, сделайте это. После этого откроется страница с форма для создания нового запроса в GitHub с уже предварительно заполненным полями. + + При помощи разметки Markdown опишите как можно подробнее, что хотите. Там, где вы видите пустые квадратные скобки (`[ ]`), проставьте `x` между скобками. Если у вас есть предлагаемое решение проблемы, напишите его. + +- **Запросить новую страницу** + + Если вы хотите добавить что-то новое, но вы не уверены, на какую страницу документации это сделать или считаете, что новая информация не вписывается в существующие страницы, всё равно создайте ишью. Вы можете либо перейти на страницу документации, куда, по вашему мнению, нужно добавить новую информацию и создать заявку прямо с этой страницы, либо перейти по адресу [https://github.com/kubernetes/website/issues/new/](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" явно не несёт ничего полезного или чтобы на него реагировали. + [Нормы поведения](/community/code-of-conduct/) также применяется к общению в GitHub-репозиториях Kubernetes. + +## Участие в дискуссиях SIG Docs + +Команда SIG Docs общается следующими способами: + +- [Зарегистрируйтесь в Slack-канале Kubernetes](http://slack.k8s.io/), а затем присоединитесь к каналу `#sig-docs`, где мы в режиме реального времени обсуждаем всё, что связано с документацией. И не забудьте представиться! +- [Подпишитесь на список рассылки `kubernetes-sig-docs`](https://groups.google.com/forum/#!forum/kubernetes-sig-docs), где проходят более общие дискуссии и принимаются официальные решения. +- Участвуйте в [еженедельной видеовстрече IG Docs](https://github.com/kubernetes/community/tree/master/sig-docs), которая анонсируется в Slack-канале и списке рассылки. В данный момент эти встречи проводятся в Zoom, поэтому вам необходимо загрузить клиент Zoom или позвонить по телефону. + +{{< note >}} +Вы всегда можете узнать когда будет очередное еженедельное собрание SIG Docs в [календаре собраний сообщества Kubernetes](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles). +{{< /note >}} + +## Улучшение существующего текста + +Чтобы улучшить текущее содержимое документации, вам нужно открыть _пулреквест (pull request, PR)_ после того, как вы сделаете _копию (fork)_ оригинального репозитория. Эти два термина [относятся к GitHub](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/). +Для начала работы, которая показана в этом разделе, вам не нужно знать всё про эти понятия, так как вы всё можете делать в своём браузере. Когда вы перейдете к продвинутому руководству участника документации, тогда вам понадобиться пополнить свои знания Git. + +Примечание. Разработчики кода Kubernetes. Если вы документируете новую функцию для предстоящего выпуска Kubernetes, ваш процесс будет немного другим. См. Документирование функции для руководства по процессу и информации о сроках. + +{{< note >}} +**Для разработчиков кода Kubernetes**: если вы документируете новую функциональность для новой версии Kubernetes, то процесс рассмотрения будет немного другим. Посетите страницу [Документирование функциональности](/docs/contribute/intermediate/#sig-members-documenting-new-features), чтобы узнать про процесс и информацию о крайних сроках. +{{< /note >}} + +### Подписание CLA-соглашения CNCF {#sign-the-cla} + +Прежде чем внести вклад в код или документацию Kubernetes, вам **обязательно** следует прочитать [руководство для участников](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md) и [подписать лицензионное соглашение участника (Contributor License Agreement, CLA)](https://github.com/kubernetes/community/blob/master/CLA.md). +Не переживайте — подписание не займет много времени! + +### Поиск задач для работы + +Если вы уже нашли что исправить, просто следуйте инструкциям ниже. Для этого вам не обязательно [создавать ишью](#file-actionable-issues) (хотя вы, безусловно, пойти этим путём). + +Если вы хотите ещё не определились с тем, над чем хотите поработать, перейдите по адресу [https://github.com/kubernetes/website/issues](https://github.com/kubernetes/website/issues) и найдите ишью с меткой `good first issue` (вы можете использовать [эту](https://github.com/kubernetes/website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) ссылку для быстрого поиска). Прочитайте комментарии, чтобы убедиться что нет открытого пулреквеста для решения текущей ишью, а также, что никто другой не оставил комментарий, что он работает над этой задачей в последнее время (как правило, 3 дня). Добавьте комментарий, что вы хотели бы заняться решением этой задачи. + +### Выбор правильной ветки в Git + +Самым важный момент в создании пулреквестов — это выбор нужной ветки для вашей работы. Используйте эти рекомендации, чтобы принять верное решение: + +- Используйте ветку `master` для исправления ошибок в текущей документации, либо чтобы улучшить существующий текст. +- Используйте ветку `master` для документирования функциональности в текущей версии Kubernetes, для которой отсутствовала документация. Прежде всего вам нужно написать документацию на английском языке, а затем команды по переводам подхватят это изменение, чтобы актуализировать перевод. +- Если вы работаете над переводом, вам нужно следовать соглашению в этой конкретной локализации. Чтобы понять это, вы можете другие пулреквесты (подсказка: `is:pr is:merged label:language/xx`) + {{< comment >}}Localization note: when localizing that tip, replace `xx` + with the actual ISO3166 two-letter code for your target locale.{{< /comment >}} + - Некоторые команды локализации работают с пулреквестами, которые ориентированы на ветку `master` + - Другие команды локализации работают с рядом долговечных веток, периодически сливая их в ветку `master`. Такая ветка именуется как dev-\-\.\, например, `dev-{{< release-branch >}}-ja.1`. +- Если вы пишете или обновляете документацию к выпуску грядущего изменения, то вам необходимо знать мажорную и минорную версию Kubernetes, в которой это изменение впервые появится. + - Например, если переключатель возможностей (feature gates) JustAnExample должен измениться с альфа-версии на бета-версию в следующей минорной версии, вам необходимо знать номер этой версии. + - Найдите ветку выпуска, названную для этой версии. Например, функциональность, которая изменились в выпуске v{{< release-branch >}}, будет документирована в ветке `dev-{{< release-branch >}}`. + +Если вы все еще не уверены, какую ветку выбрать, спросите в Slack-канале `#sig-docs` или посетите еженедельную встречу SIG Docs, чтобы внести ясность. + +### Отправка пулреквеста + +Следуйте описанным ниже шагам, чтобы создать пулреквест для улучшения документации Kubernetes. + +1. На странице, которую вы хотите отредактировать, щелкните на иконку карандаша в правом верхнем углу. Откроется новая страница на GitHub с небольшой подсказкой. +2. Если вы ранее не делали копию репозитория документации Kubernetes, вам будет предложено это сделать. Создайте копию репозитория под своим логином GitHub, а не в организации, в которой вы состоите. URL-адрес копии репозитория будет выглядит как `https://github.com//website`, в случае у вас нет репозитория с таким же названием. + + Поскольку у вас нет доступа к оригинальному репозиторию и соответственно вы не можете отправлять напрямую изменения в основную ветку, вам нужно сделать копию репозитория Kubernetes. + +3. Откроется редактор GitHub для редактирования исходного файла в формате Markdown. Внесите свои изменения. Под редактором заполните форму **Propose file change**. Первое поле — краткое содержание вашего сообщения коммита, оно должно содержать не более 50 символов. Второе поле является необязательным, в нём вы можете подробно расписать суть ваших изменений. + + {{< note >}} + Не ссылайте на другие ишью или пулреквесты на GitHub в сообщении коммита. Вы можете сослаться на них в тексте пулреквеста. +{{< /note >}} + + Нажмите на кнопку **Propose file change**. Изменения в файле записываются в виде коммита в новой ветке вашей копии репозитория, которая автоматически будет иметь имя что-то вроде `patch-1`. + +4. На следующей странице вам будут показаны различия в вашей ветке (поля выбора **head fork** и **compare**) с текущим состоянием **оригинального репозитория (base fork)** в **основной ветке (base)** (по умолчанию ветка `master` в репозитории `kubernetes/website`). Вы можете выбрать другое значение в полях выбора, но не делайте этого сейчас. Сравните различия и если всё верно, нажмите кнопку **Create pull request**. + + {{< note >}} + Если вы не хотите создавать пулреквест в данный момент, это можно сделать позже, если перейти на страницу репозитория сайта Kubernetes или вашей копии репозитория. На сайте GitHub вам предложит открыть пулреквест, если он обнаружит новую ветку в вашей копии репозитория. +{{< /note >}} + +5. Отобразится форма с заголовком **Open a pull request**. Название пулреквеста будет содержать краткое описание из сообщения коммита, хотя вы можете изменить его при необходимости. В описании пулреквеста будет остальная информация из сообщения коммита (если оно есть) и небольшой шаблон с текстом. Прочитайте текст шаблона и сделайте то, что там описано, а затем удалите этот шаблонный текст. Если вы добавите в описание пулреквест `fixes #<000000>` или `closes #<000000>`, где `#<000000>` - номер связанной заявки, то GitHub автоматически закроет указанную заявку при слиянии пулреквеста. Оставьте флажок **Allow edits from maintainers** отмеченным. Нажмите на кнопку **Create pull request**. + + Поздравляем! Ваш пулреквест добавлен в список [пулреквестов](https://github.com/kubernetes/website/pulls). + + Через несколько минут вы сможете просмотреть версию сайта с изменениями в вашем пулреквесте. Перейдите в низ страницы пулреквеста на вкладке **Conversation** и там нажмите на ссылку **Details** рядом с проверкой `deploy/netlify`. По умолчанию она откроется в текущей вкладке. + + {{< note >}} + Пожалуйста, открывайте пулреквест, изменения которого затрагивают только один язык. Например, если вам нужно одинаково изменить один и тот же пример кода в нескольких языках, откройте по отдельному пулреквесту для каждого языка. + {{< /note >}} + +6. Ожидайте, когда проверят ваш пулреквест. Как правило, рецензенты выбираются авматоматически ботом `k8s-ci-robot`. Если рецензент попросил изменить пулреквест, вы можете сделать это, если перейдёте на вкладку **Files changed** и щёлкните на иконку с карандашом на любом изменённом файле в вашем пулреквесте. Сохранение измененного файла оформляется в виде нового коммита в ветке, указанной в пулреквесте. Если вы ожидаете новую проверку изменений от рецензента, заранее попросите его об этом не более одного раза в 7 дней. Вы также можете зайти в Slack-канал #sig-docs — это хорошее место, где можно попросить проверку пулреквеста. + +7. Если ваши изменения одобрены, то рецензент объединяет соответствующий пулреквест. Через несколько минут вы сможете сможете увидеть его в действии на сайте Kubernetes. + +Это только один из способов отправить пулреквест. Если вы уже опытный пользователь Git и GitHub, вы можете вносить изменения, используя локальный GUI-клиент или Git из терминала вместо того, чтобы использовать интерфейс GitHub для этого. Некоторые основы использования Git-клиента из командной строки обсуждаются в [продвинутом](/docs/contribute/intermediate/) руководстве участника. + +## Просмотр пулреквестов в документацию + +Новички документации могут обозревать пулреквесты. Вы можете изучить кодовую базу и завоевать доверие к себе со стороны коллег-участников. Документация на английском — это первоисточник содержимого. Мы общаемся на английском языке во время еженедельных встреч и в объявлениях сообщества. Владение английским языком может быть разным, поэтому используйте простой и прямой язык в своих обзорах пулреквестов. Полезные обзоры фокусируются как на мелких деталях, так и на потенциальном влиянии изменений. + +Обзоры не носят «обязательный характер», это означает, что только ваша проверка не приведет к слиянию пулреквеста. Тем не менее, это не делает ваши обзоры бесполезными. Даже только просмотр изменений в пулреквеста поможет вам понять как происходит рабочий процесс, какие могут быть трудности и проблемы. Перед проверкой пулреквестов ознакомьтесь с [руководством по содержанию](/docs/contribute/style/content-guide/) и [руководством по оформлению](/docs/contribute/style/style-guide/), чтобы узнать, каким должен быть содержимое и как оно должно быть оформлено.. + +### Рекомендации + +- Будьте вежливы, внимательны и помогайте другим +- Не забывайте отмечать также положительные стороны пулреквеста +- Будьте чутким и думайте, как ваши комментарии могут быть восприняты +- Проявите добрые намерения и задавайте уточняющие вопросы +- Опытным участникам: помогайте новым участникам, их работа требует глаз да глаз + +### Поиск и проверка пулреквеста + +1. Перейдите по URL-адресу [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls). Вы увидите список всех пулреквестов в репозиторий сайта Kubernetes и его документации. + +2. По умолчанию открываются открытые пулреквесты (статус `open`), поэтому вы не увидите закрытых или принятых пулреквестов. Рекомендуется добавить дополнительный фильтр `cncf-cla: yes`, а также для вашей первой проверки пулреквеста неплохо применить ещё и `size/S` и `size/XS`. Метка с размером назначается автоматически в зависимости от количества изменённых строк кода в пулреквесте. Вы можете применить фильтры, используя поля выбора в верхней части страницы, либо воспользоваться [этой ссылкой](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+yes%22+label%3Asize%2FS) для просмотра небольших пулреквестов. Все фильтры объединены в логическое `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](https://docs.google.com/forms/d/e/1FAIpQLSdMpMoSIrhte5omZbTE7nB84qcGBy8XnnXhDFoW0h7p2zwXrw/viewform), либо же выполнить следующие действия. + +1. [Подпишите CLA](#sign-the-cla), если вы еще этого не сделали. +2. Изучите разметку Markdown у текущих постов блога в репозитории сайта. +3. Напишите свою статью в вашем любимом текстовом редакторе. +4. По ссылке из второго шага нажмите на кнопку **Create new file**. Скопируйте из своего редактора текст и вставьте в многострочное поле. Назовите файл так, чтобы он соответствовал предлагаемому заголовку статьи в блоге, но не указывайте дату в имени файла. Рецензенты блога будут работать с вами над окончательным именем файла и датой публикации записи. +5. Когда вы сохраните файл, начнётся описанный выше процесс принятия пулреквеста в GitHub. +6. Рецензент блога рассмотрит вашу статью и вместе с вами будет работать над ее улучшением. Когда запись в блоге будет одобрена, будет известна дата публикации вашей статьи. + +## Отправка примеров использования + +В примерах использования показывается, как организации используют Kubernetes для решения собственных реальных проблем. Они написаны в сотрудничестве с маркетинговой командой Kubernetes, которой занимается {{< glossary_tooltip text="CNCF" term_id="cncf" >}}. + +Ознакомьтесь с [существующими примерами использования](https://github.com/kubernetes/website/tree/master/content/en/case-studies). Воспользуйтесь [формой добавления нового примера использования Kubernetes](https://www.cncf.io/people/end-user-community/), чтобы поделиться своим опытом. + +{{% /capture %}} + +{{% capture whatsnext %}} + +Если вы хорошо поняли темы, затронутые в этом разделе, но хотите глубже взаимодействовать с командой документации Kubernetes, прочитайте [расширенное руководство по участию в документации](/docs/contribute/intermediate/). + +{{% /capture %}}