Инструкции по вкладу

Проект Helm принимает вклады через запросы на вытягивание (pull requests) в GitHub. Этот документ описывает процесс, чтобы помочь вам сдать свой вклад на рассмотрение.

Отчёт о проблемах безопасности

Большинство времени, когда вы находите ошибку в Helm, она должна быть отмечена с помощью GitHub issues. Однако, если вы сообщаете о уязвимости безопасности, пожалуйста, отправьте отчет по электронной почте на адрес cncf-helm-security@lists.cncf.io. Это даст нам возможность попробовать исправить проблему до того, как она будет использована злоумышленниками.

Helm v3 и v4

Helm v4 находится в разработке на ветке main. В период разработки Helm v4 и некоторое время после его выпуска, Helm v3 продолжит поддерживаться и развиваться на ветке dev-v3. Helm v3 будет получать исправления ошибок и обновления для новых версий Kubernetes. Новые функции и значительные изменения будут реализованы в Helm v4. Для обратной совместимости функции могут быть перенесены в Helm v3 при наличии исключения. Ошибки должны быть сначала исправлены в Helm v4, а затем перенесены в Helm v3.

Подпишите вашу работу

Подпись — это простая строка в конце объяснения коммита. Все коммиты должны быть подписаны. Ваша подпись свидетельствует о том, что вы создали патч или имеете право представить этот материал. Правила довольно простые, если вы можете удостовериться в следующем (из developercertificate.org):

Свидетельство разработчика о происхождении
Версия 1.1

Авторское право (C) 2004, 2006 The Linux Foundation и его участников.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Каждому разрешается делать и распространять точные копии этого лицензионного документа,
но изменять его запрещено.

Свидетельство разработчика о происхождении 1.1

При внесении вклада в этот проект, я свидетельствую, что:

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

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

(c) Вклад был предоставлен мне непосредственно другим человеком, который свидетельствовал (a), (b) или (c),
и я не изменил его.

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

Затем просто добавьте строку ко всем сообщениям коммитов Git:

Signed-off-by: Иван Петров <ivan.petrov@example.com>

Используйте свое настоящее имя (извините, никаких псевдонимов или анонимных вкладов).

Если вы установили свои конфигурации Git user.name и user.email, вы можете автоматически подписывать свои коммиты командой git commit -s.

Для обновления ваших конфигураций Git с user.email используйте следующую команду:

git config --global user.email ivan.petrov@example.com

Эта команда обновляет ваши конфигурации Git с user.name:

git config --global user.name "Иван Петров"

Примечание: Если информация о ваших конфигурациях Git установлена правильно, просмотр информации git log вашего коммита будет выглядеть примерно так:

Автор: Иван Петров <ivan.petrov@example.com>
Дата:   Чт фев 2 11:41:15 2018 -0800

    Обновление README

    Signed-off-by: Иван Петров <ivan.petrov@example.com>

Обратите внимание, что строки Автор и Signed-off-by совпадают. Если они не совпадают, ваш запрос будет отклонен автоматической проверкой DCO.

Каналы поддержки

Независимо от того являетесь ли вы пользователем или вкладчиком, официальные каналы поддержки включают:

• Issues
• Slack:
  • Пользователи: #helm-users
  • Вкладчики: #helm-dev

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

Майлстоны

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

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

Вопросы и запросы на вытягивание, которые считаются несовместимыми с предыдущими версиями, могут быть добавлены в обсуждаемые пункты для Helm 4 с label:v4.x. Вопрос или запрос на вытягивание, которым мы еще не уверены, будем ли мы решать, не будет добавлен ни в какой майлстон.

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

Семантическая версионность

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

Мы также остаемся приверженными тому, чтобы не менять общедоступные определения Go-библиотек внутри директории pkg/ нашего исходного кода способом, нарушающим обратную совместимость.Для более подробной информации о правилах обратной совместимости для минорных и патч-выпусков Helm, прочтите HIP-0004.

Для краткого описания наших правил обратной совместимости для выпусков между 3.0 и 4.0:

• Командные строки, флаги и аргументы должны быть обратно совместимы;
• Форматы файлов (например, Chart.yaml) должны быть обратно совместимы;
• Любая диаграмма, работавшая на предыдущей версии Helm 3, должна работать на новой версии Helm 3 (за исключением случаев, когда сам Kubernetes изменился или диаграмма работала благодаря эксплуатации ошибки);
• Функциональность хранилищ диаграмм должна быть обратно совместима;
• Go-библиотеки внутри pkg/ должны оставаться обратно совместимыми, хотя код внутри cmd/ и internal/ может быть изменен от выпуска к выпуску без уведомления.

Вопросы

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

Типы вопросов

Существует 5 типов вопросов (каждый со своим соответствующим тикетом):

• question/support: Эти вопросы предназначены для поддержки или запросов функциональности, которые мы хотим иметь записью для будущего использования. Обычно это вопросы, слишком сложные или большие, чтобы хранить их в канале Slack или имеют особенный интерес для всей группы. В зависимости от обсуждения, эти вопросы могут стать feature или bug.
• proposal: Используется для предметов (как этот), которые предлагают новые идеи или функциональность, требующие большего обсуждения сообщества. Это позволяет получить отзывы от других членов сообщества перед тем, как функциональность будет фактически разработана. Это не требуется для малых добавлений. Конечное решение о необходимости предложения принадлежит основным поддерживателям. Все вопросы, являющиеся предложениями, должны иметь как тикет, так и название вопроса в виде "Proposal: [остальная часть названия]".
• feature: Эти вопросы отслеживают конкретные запросы на функциональность и идеи до тех пор, пока они не завершены. Они могут эволюционировать из proposal или могут быть представлены отдельно в зависимости от размера.
• bug: Эти вопросы отслеживают ошибки в коде.
• docs: Эти вопросы отслеживают проблемы с документацией (например, недостающую или неполную).

Жизненный цикл вопросов

Жизненный цикл вопросов главным образом управляем основными поддерживателями, но является полезной информацией для всех, кто вносит вклад в Helm. Все типы вопросов следуют одному общему жизненному циклу. Различия отмечаются ниже.

1. Создание вопроса
2. Диагностика
   • Управляющий, ответственный за диагностику, примет необходимые метки для вопроса. Это включает метки для приоритета, типа и метаданных (например, good first issue).
   • (Если необходимо) Чистка названия для четкого и ясного указания вопроса. Также убедитесь, что предложения начинаются с "Proposal: [остальная часть названия]".
   • Добавление вопроса к соответствующему майлстону. Если возникают вопросы, не беспокойтесь о добавлении вопроса к майлстону до тех пор, пока вопросы не будут решены.
   • Мы стараемся выполнять этот процесс по крайней мере один раз в рабочий день.
3. Обсуждение
   • Вопросы, отмеченные как feature или proposal, должны иметь план развития Helm (HIP). Смотрите Предложение идеи. Меньшие улучшения качества жизни освобождаются от этого требования.
   • Вопросы, отмеченные как feature или bug, должны быть связаны с запросом на вытягивание, решающим их.
   • Любой, кто работает над вопросом feature или bug (будь то поддерживатель или участник сообщества), должен либо назначить вопрос себе, либо сделать комментарий в вопросе, говоря, что он берет его на себя.
   • Вопросы proposal и support/question должны оставаться открытыми до тех пор, пока они не будут решены или если они не были активны более 30 дней. Это поможет поддерживать список вопросов управляемым и уменьшить шум. Если вопросу нужно остаться открытым, метка keep open может быть добавлена.
4. Закрытие вопроса

Предложение идеи

Перед тем как предложить новую идею в проект Helm, пожалуйста, убедитесь, что вы составили предложение по улучшению Helm (HIP). Предложение по улучшению Helm — это документ-проект, который описывает новую функциональность для проекта Helm. Предложение должно содержать краткое техническое описание и мотивацию для данной функции.

Также стоит рассмотреть возможность проверки своей идеи с сообществом через почтовый список cncf-helm. Общее обсуждение идеи перед написанием предложения может сэкономить время потенциального автора. Многие идеи уже были предложены; вполне возможно, что кто-то еще в сообществе работает над аналогичной идеей или уже был создан аналогичный проект.

HIPы отправляются в репозиторий helm/community. HIP 1 описывает метод создания HIP и процесс его проверки.

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

Как сделать вклад в исправление

1. Определите или создайте связанное с вашими изменениями заявление. Если вы предлагаете более крупное изменение для Helm, см. Принятие идеи.
2. Создайте форк нужного репозитория; реализуйте и протестируйте свои изменения.
3. Отправьте запрос на слияние, убедившись, что подписали свою работу и указали связанное заявление.

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

Запросы на слияниеКак любой хороший открытый проект, мы используем запросы на слияние (Pull Requests, PR) для отслеживания изменений кода.

Жизненный цикл PR

1. Создание PR
   • PR обычно создаются для исправления определенной проблемы или являются частью других PR, которые решают конкретную проблему.
   • Мы радушно принимаем PR, находящиеся в процессе выполнения. Они являются отличным способом отслеживать важную работу, которая находится в процессе выполнения, но полезна для других участников. Если PR является работой в процессе, он обязательно должен начинаться со слова "WIP:".
   • После того, как PR готов к обзору, слово "WIP" следует удалить из названия.
   • Лучше, но не обязательно иметь PR, связанный с определенной проблемой. В некоторых случаях быстрое исправление может быть слишком большим для создания проблемы. В этом случае детали, предоставленные в описании PR, будут достаточно подробными.
2. Подготовка PR
   • Участник, ответственный за подготовку PR, должен применять правильные метки для проблемы. Это должно включать хотя бы одну метку размера (size), bug или feature, а также awaiting review после применения всех меток. Дополнительные сведения о метках представлены в разделе Метки.
   • Добавьте PR к соответствующему этапу. Это должно совпадать с этапом проблемы, которую закрывает данный PR.
3. Назначение обзоров
   • Как только обзор имеет метку awaiting review, участники могут рассматривать его при наличии свободного времени. Участник, взявший задачу, должен сам запрашивать обзор.
   • PR от члена сообщества с метками size/S или выше требуют двух одобрений от участников до слияния. Те с меткой size/XS зависят от решения участников. Для более подробной информации см. раздел Метки размера.
4. Обзор/Обсуждение
   • Все обзоры должны выполняться с помощью инструмента обзора GitHub.
   • "Комментарий" обзор используется, когда есть вопросы относительно кода, которые должны быть отвечены, но они не требуют изменений кода. Такой тип обзора не считается одобрением.
   • "Запрошенные изменения" обзор указывает, что требуется изменение кода перед тем, как он будет слит.
   • Обзорщики должны обновлять метки, если это необходимо (например, needs rebase).
5. Ответить на замечания, отвечая на вопросы или изменяя код
6. LGTM ("Любит то, что видит")
   • Когда обзорщик завершил обзор и код готов к слиянию, используется "Одобрен" обзор для сигнализации автору и другим участникам, что код был просмотрен и считается готовым к слиянию.
7. Слияние или закрытие
   • PR должны оставаться открытыми до слияния или если они не активны более 30 дней. Это поможет поддерживать очередь PR в управляемом состоянии и уменьшить шум. Если PR должна остаться открытым (например, в случае работы в процессе), можно использовать метку keep open.
   • Перед слиянием PR, обратитесь к разделу Метки размера ниже, чтобы определить, требуется ли больше одного LGTM для слияния данного PR.
   • Если владелец PR указан в файле OWNERS, этот пользователь обязательно должен слить свои собственные PR или явно запросить другого владельца сделать это вместо него.
   • Если владелец PR не указан в OWNERS, любой основной участник может слить PR.

PR документации

Документационные PR должны быть сделаны на репозиторий документов: https://github.com/helm/helm-www. Поддержание актуальной документации для Helm очень желательно и рекомендовано для всех изменений, доступных пользователям. Актуальная и полезная документация критически важна для эффективного представления поведения Helm широкому кругу пользователей.

Мелкие, случайные изменения/PR для Helm, которые вводят изменения, доступные пользователям, и которым потребуется обновление документации, должны применять метку docs needed. Большие изменения, связанные с HIP, должны отслеживать документацию через этот HIP. Метка docs needed не блокирует PR, и участники/обзорщики PR должны применять своё усмотрение, применяя эту метку.

Профилирование PR

Если ваш вклад требует профилирования для проверки использования памяти и/или ЦПУ, вы можете установить переменные окружения HELM_PPROF_CPU_PROFILE=/path/to/cpu.prof и/или HELM_PPROF_MEM_PROFILE=/path/to/mem.prof для сбора данных профилирования во время выполнения для анализа. Вы можете использовать инструмент pprof Go для просмотра результатов.

Пример анализа собранного профилировочного данных

HELM_PPROF_CPU_PROFILE=cpu.prof HELM_PPROF_MEM_PROFILE=mem.prof helm show all bitnami/nginx

# Визуализировать графики. Вам потребуется установленный пакет graphviz в системе
go tool pprof -http=":8000" cpu.prof

go tool pprof -http=":8001" mem.prof

Триажер

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

Метки

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

Общие| Метка | Описание |

| ----- | ----------- | | bug | Означает, что проблема является багом или PR является исправлением бага | | критический | Означает, что проблема или PR является критической. Это значит, что решение PR или проблемы является первостепенной задачей и должно быть решено как можно скорее | | документация | Индикатор того, что проблема или PR является изменением документации | | функциональность | Означает, что проблема является запросом на функциональность или PR является реализацией функциональности | | сохранить открытым | Означает, что проблема или PR должна быть сохранена открытой более 30 дней бездействия | | переформатировать | Индикатор того, что проблема является переформатированием кода и не является исправлением бага или добавлением дополнительной функциональности |

Проблемы

PR

Размерные метки

Размерные метки используются для указания, насколько "опасен" PR. Ниже приведены руководства по назначению этих меток, но конечное решение остаётся за участниками. Например, даже если PR меняет всего 30 строк кода в одном файле, но затрагивает ключевые функции, он вероятно будет помечен как size/L, так как требует согласования от нескольких людей. Наоборот, PR, добавляющий небольшую функциональность, но требующий ещё 150 строк тестов для покрытия всех случаев, мог бы быть помечен как size/S, даже если количество строк больше, чем указано ниже.

Любые изменения от сообщества, помеченные как size/S или выше, должны быть тщательно протестированы перед слиянием и всегда требуют одобрения от двух основных участников. PR, отправленные основным участником, независимо от размера, требуют одобрения только от одного дополнительного участника. Это гарантирует, что минимум два участника осведомлены обо всех значительных PR, внесённых в кодовый базис.