Вклад в Zadig

Сначала большое спасибо за использование Zadig!

Zadig — это распределённая открытая система непрерывной доставки, которая отличается от других систем CI/CD тем, что обеспечивает высокую доступность CI/CD и включает множество лучших практик для различных технологических сценариев.

Развитие Zadig невозможно без вашей поддержки. Мы рады любым вкладам, будь то исправление опечаток, обновление ссылок в документах или полное внедрение нового функционала от дизайна до реализации. Если вы хотите внести свой вклад в проект, пожалуйста, прочитайте нижеуказанные рекомендации.

Содержание- Вклад в Zadig

• Содержание
• Предварительные условия
• Настройка окружения
• Метод внесения вклада 1 — Отправка проблемы
  • Как будет обработана отправленная проблема?
• Метод внесения вклада 2 — Изменение документов
  • Простое изменение документов
  • Дополнительное изменение документов
• Метод внесения вклада 3 — Отправка кода
  • Простое изменение кода
  • Дополнительное изменение кода
  • Обновление документации API
• Ресурсы для вкладчиков
  • Указания по PR / Commit
  • Дорога развития для вкладчиков
  • Как получить помощь
  • Другие ресурсы## Предварительные условия

Каждый коммит должен содержать сертификат участника разработки (Developer Certificate of Origin). Это легкая процедура, подробнее можно узнать здесь.

Также просим вас следовать правилам поведения сообщества Code of Conduct. Хорошее развитие Zadig зависит от здорового сообщества, поэтому мы призываем всех его поддерживать.

Настройка окружения

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

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

1. Если вы ищете задачи для начала работы, обратитесь к метке #good-first-issue, возможно, что-то из них будет вам интересно.
2. Если вы ищете более продвинутые возможности для вклада, просмотрите задачи с меткой #help-wanted.
3. Если вы хотите исправить ошибки, проверьте задачи с меткой #bugs.

Способы вклада 1 - Отправка issueЕсли вы хотите сообщить о проблеме, связанной с безопасностью, пожалуйста, не отправляйте её через issue, а напишите на электронную почту contact@koderover.com. Если ваша проблема не связана с безопасностью, продолжайте чтение этого раздела.Когда вкладчики отправляют issue, им следует учитывать следующие пять типов:

1. documentация
2. ошибка
3. запрос на новую функцию
4. вопрос
5. усовершенствование

Если вкладчик уверен, что его issue относится к конкретному или нескольким сервисам, рекомендуется добавить соответствующий label сервиса: подробнее найдите метки с префиксом сервис/; если нет уверенности, можно не добавлять, наши maintainers добавят их позже.

Сначала проверьте наш список открытых issue, чтобы убедиться, что вы не отправляете повторяющийся issue. После того как вы удостоверились, что issue уникален, выберите один из вышеупомянутых labels и заполните шаблон issue, максимально подробно объясняя свой вопрос — принцип заключается в том, чтобы любой другой человек мог легко понять контекст вашего вопроса.

Как будет обработан ваш issue после отправки?Наши проектные administrаторы будут отслеживать все issue и выполнять необходимые действия по их обработке:

1. Они проверят, правильно ли были добавлены пять указанных выше меток к новому созданному issue. Если нет, они произведут необходимые изменения.
2. В то же время они решат, следует ли принять issue, см. следующий пункт.
3. Если применимо, они могут добавить одно из четырех новых тегов к issue:
   1. duplicate: повторяющийся issue
   2. wontfix: принято решение не исправлять. Администратор объясняет конкретные причины отказа от исправления, такие как работа в соответствии с намеченной целью, устарелость, невозможность реализации, выход за рамки задачи.
   3. good first issue: см. выше, issue, подходящий для новичков.
   4. good intermediate issue: см. выше, более продвинутый issue, приглашающий участников сообщества к участию.
4. Если issue не был закрыт, он теперь официально может быть взят на выполнение (сообщение на issue).
5. Администратор также регулярно проверяет и очищает все issues, удаляя просроченные issues.

Способ вклада 2 — Изменение документации### Простое изменение документации

Для очень простых изменений документации, таких как исправление опечатки или обновление ссылки, нет необходимости проходить через какой-либо процесс; просто создайте запрос на вытягивание (pull request, PR). Наши поддерживатели (maintainers) проверят ваш запрос. Для конкретных требований к PR, пожалуйста, обратитесь к нашему руководству по PR/Commit.

Расширенное изменение документации

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

Способ вклада 3 — Внесение изменений в код

Для любых изменений в коде вам необходимо иметь соответствующую задачу (issue) для отслеживания этих изменений: будь то существующая задача или создание новой задачи.

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

Для простых изменений в коде наши руководства следующие:

1. Вы можете описать своё решение в соответствующей задаче, чтобы получить отзывы; конечно, если вы уверены, что ваши изменения просты и очевидны, и они маловероятно вызовут проблемы, вы можете пропустить этот шаг.
2. Делайте соответствующие изменения в форке вашего репозитория — подробные руководства см. в разделе о разработке Zadig.
3. Следуйте нашему руководству по PR/Commit, чтобы отправить PR, наши поддерживатели проверят его.
4. Если вы добавили или изменили какие-либо API сервисов aslan, вам следует обновить нашу документацию по API.

Расширенные изменения в кодеДля менее очевидных или немного более сложных изменений в коде:

1. Вам следует сначала создать документ с описанием дизайна:
   1. Скопируйте наш шаблон для описания дизайна шаблон Zadig.
   2. Используйте этот шаблон для описания того, что вы хотите сделать, ваших концепций дизайна и соответствующих предостережений, таких как изменения в базе данных, вопросы совместимости и так далее.
   3. Документ должен быть простым и понятным.
2. Название вашего документа должно соответствовать формату yyyy-MM-dd-название-вашего-проекта.md, и он должен быть помещён в директорию community/rfc. Для этого проекта создайте отдельный Pull Request (PR), который будет проверяться нашими maintainers.
3. Если ваш дизайн будет принят и PR будет объединён, вы сможете применить изменения согласно вашему документу.
4. Мы настоятельно рекомендуем поддерживать атомарность PR, то есть если ваш проект можно разделить на более мелкие задачи, мы рекомендуем это сделать и отправить отдельный PR для каждой задачи.
5. Для каждого из этих мелких подзадач, используйте вышеописанные руководства по легким изменениям кода.

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

Документация для aslan доступна здесь: мы используем Swag для автоматического генерирования документов Swagger; Swag создаёт документацию на основе комментариев к API в коде (следуя формату swag declarative API comments).

Поэтому если вы добавили или изменили какие-либо API для aslan, вам следует выполнить следующие действия:

1. Добавьте подходящие комментарии к вашим API, следуя формату swag declarative API comments.
2. Используйте следующую команду для обновления документации API для aslan:

cd [ваш корневой путь zadig]

make swag

Дополнительные детали см. в разделе Swag CLI.

Примечание: если сгенерированная doc/docs.go содержит "github.com/alecthomas/template" (ранние версии Swag), замените это на стандартную библиотеку "text/template".

3. Проверьте сгенерированную документацию API в вашей тестовой среде, чтобы убедиться, что она соответствует вашим ожиданиям. Относительный путь к документации — /api/aslan/apidocs/index.html.

Ресурсы для участников проекта

Указания по PR / Commit- Пожалуйста, следуйте нашему шаблону PR и максимально подробно описывайте свой PR.

• Поддерживайте атомарность каждого PR, и пусть каждое сообщение коммита будет кратким, понятным и точным.
• Не забудьте подписать каждый коммит DCO.
• Мы рекомендуем рано создавать PR; нет необходимости ждать окончания всех работ перед созданием PR. Однако помните, что следует добавить префикс "WIP" к названию PR — "WIP: [название]". Когда PR готов к проверке, удалите этот префикс. После этого наш maintainer начнет его проверять.
• Убедитесь, что ваш PR проходит все тесты.
• Для стиля кода обратитесь к официальной Go Code Review Comments.
• Добавьте соответствующий label к своему PR, как указано в способах вклада 1 - отправка issue.
• Полностью протестируйте ваш код после внесения изменений — см. как отладить код.### Путь продвижения в качестве участника проектаУ нас есть четкая схема продвижения для разработчиков, подробнее см. наш документ GOVERNANCE.

Как получить помощь

• Электронная почта: contact@koderover.com
• Присоединяйтесь к каналу Slack

Другие ресурсы

• Сотрудники, поддерживающие проект