Как внести свой вклад

Добро пожаловать

Добро пожаловать в руководство по работе над Глоссарием Cloud Native. Благодарим за проявленный интерес! Поучаствовать в развитии проекта можно разными способами:

1. Поработать над существующим Issue
2. Предложить новое определение
3. Дополнить существующее определение
4. Локализовать глоссарий

Общие сведения о глоссарии CNCF

Цель этого глоссария — упростить знакомство с нативными облачными (cloud native) технологиями, которые печально известны своей сложностью и запутанностью, и сделать их более доступными для пользователей.

Материалы Глоссария Cloud Native хранятся в репозитории на GitHub. В нем вы найдете список Issues, Pull Request’ов (PRs) и обсуждений, касающихся глоссария.

Кто может внести свой вклад?

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

Богатый опыт просто необходим, потому что объяснить сложные понятия доступным языком бывает очень непросто. Может показаться, что создать простое и понятное определение достаточно легко. На самом деле это не так: конечная простота является результатом напряженной работы и сотрудничества многих экспертов по cloud native-технологиям.

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

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

Перед началом работы

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

1. Создайте учетную запись на GitHub’е, если у вас ее еще нет.
2. Подпишите Лицензионное соглашение с контрибьютором (Contributor License Agreement) (CLA).
3. Проверьте подпись к коммитам.
4. Включите режим vigilant в GitHub-аккаунте: ваши коммиты будут помечаться статусом Verified.

Лучшие практики

Чтобы облегчить рецензирование, используйте смысловой перенос строк (одна строка на предложение). Рекомендуем ознакомиться со шпаргалкой по Markdown, чтобы правильно форматировать md-текст на GitHub’е (например, гиперссылка, жирный шрифт, курсив). При именовании файлов .md используйте строчные буквы, дефисы вместо пробелов для разделения слов и избегайте скобок.

Руководство по стилю

Руководство по стилю содержит требования к форматированию и содержанию документов, а также советы о том, как повысить эффективность работы.

Присоединяйтесь к сообществу Глоссария!

Регулярным контрибьюторам рекомендуем присоединиться к Рабочей группе по глоссарию (ее заседания проходят ежемесячно). График встреч можно найти в календаре CNCF. Также можно пообщаться с хранителями и соавторами в Slack-канале CNCF #glossary — мы будем рады знакомству с вами!

Работа над существующим Issue

Список открытых Issues можно найти в репозитории глоссария на GitHub’е. Отфильтровать их можно с помощью лейблов (например, English language, help needed, good first issue).

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

Выбрав термин, отпишитесь в его Issue:

Сообщите хранителям в канале #glossary в рабочем пространстве CNCF в Slack, призвав @iamnoah, @nate-double-u, @Seokho Son, @Jihoon Seo и/или @castrojo, чтобы они наверняка увидели ваше уведомление.

Дальнейшие шаги описаны в разделе Создание нового термина (открываем PR).

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

Предложить новый термин

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

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

1. Как и где искать шаблоны для Issues и новых терминов.
2. Как закрепить Issue за собой.
3. Как решать проблемы с проверкой орфографии failures.

Как создать Issue

Перейдите в репозиторий глоссария на GitHub’е и нажмите “New issue”.

Выберите “Request to add a new term (English)” (Запрос на добавление нового термина на английском языке) из списка шаблонов.

Примечание: пока новые термины принимаются только на английском языке. Если у вас есть идея для нового определения, но вы затрудняетесь переложить ее на английский язык, свяжитесь с хранителями русской версии в канале #glossary-localization-russian — мы поможем.

Добавьте свой термин, ответьте на вопросы, поставьте галочки и нажмите “Submit new issue”. Если вы просто предлагаете новый термин, больше ничего делать не нужно. Если вы хотите поработать над определением, продолжайте читать.

Триаж Issue

Далее хранители проведут триаж Issue. А именно, решат, стоит ли включать термин в глоссарий. Принимаются далеко не все термины: чтобы попасть в глоссарий, они должны устояться в мире cloud native-технологий и широко там использоваться.

Сообщите хранителям в Slack’е о новом термине (позовите @iamnoah, @nate-double-u, @Seokho Son, @Jihoon Seo и/или @castrojo).
Если вы хотите поработать над определением, сообщите об этом хранителям, и они закрепят термин за вами.

Отправка нового термина (создаем PR)

Как указано в Руководстве по стилю, настоятельно рекомендуется начинать с документа в Google или в Word.

Когда термин будет готов к отправке, перейдите в директорию content (на вкладке <>code)…

…затем в “en” (для английского языка) или в директорию языка локализации…

…и выберите _TEMPLATE.md

Скопируйте его содержимое……

…и вернитесь в папку “en” или языка локализации. Нажмите “Add file” и выберите “Create new file”.

Включите название термина в URL, как описано в разделе Лучшие практики. Добавьте к нему расширение .md (без этого расширения будет невозможно предварительно просмотреть файл). Теперь вставьте шаблон в поле с содержимым файла. Скопируйте и вставьте текст определения в файл. Чтобы проверить markdown-код на соответствие требованиям из раздела Лучшие практики, нажмите “Preview”.

Прокрутите вниз и введите описание коммита. Затем нажмите “Commit new file” и…

…перейдите к созданию PR’а. Добавьте его описание и нажмите на “Create pull request”:

После этого PR должен появиться на вкладке “Pull requests”.

Изменение существующего термина

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

Запросить изменения с помощью Issue

Чтобы сообщить о проблеме с термином, можно воспользоваться опцией “Сообщить о проблеме” на странице Глоссария CNCF. Перейдите на страницу с соответствующим термином и нажмите “Сообщить о проблеме”. Автоматически откроется форма для создания Issue:

Опишите свои предложения и объясните, почему они необходимы. Нажмите “Submit new issue”.

Изменить термин напрямую

Чтобы изменить термин и внести свои предложения, нажмите “Редактировать страницу”.

Откроется страница термина на GitHub’е. Внесите свои правки и создайте PR. Обратитесь к разделу Лучшие практики выше и ознакомьтесь с Руководством по стилю, чтобы убедиться, что следуете рекомендациям.

Помощь в локализации глоссария

Чтобы помочь в локализации глоссария на целевой язык, присоединитесь к каналу #glossary-localizations в рабочем пространстве CNCF в Slack’е и дайте нам знать. Можно войти в существующую команду или создать новую (чтобы узнать, что для этого нужно, прочитайте Руководство по локализации). Пожалуйста, ознакомьтесь с руководством Как внести свой вклад на целевом языке, чтобы узнать об особенностях работы соответствующей команды.

Проверка орфографии

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

• PR содержит орфографические ошибки.
• PR содержит слова, которые не зарегистрированы в списке слов.

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

1. В вашем PR найдите файл “wordlist.txt”.
2. Нажмите “Отредактировать этот файл” (“Edit this file”) и добавьте недостающие слова в алфавитном порядке.
3. Добавьте сообщение коммита и выберите “Подписать и предложить изменения” (“Sign off and propose changes”).

Примечание: при проверке орфографии регистр (строчные/прописные буквы) во внимание не принимается.

Это руководство было обновлено на основе шаблонов из проекта The Good Docs Project.