Руководство для участников MOSN

MOSN выпущен под лицензией Apache 2.0 и следует стандартному процессу разработки на Github, используя Github Issue для отслеживания проблем и объединяя Pull Request в ветку master. Этот документ поможет вам понять, как участвовать в разработке.

Перед отправкой Pull Request необходимо подписать Лицензионное соглашение участника (CLA). Хотя подписание CLA не даёт вам права на отправку в основной репозиторий, это означает, что мы можем принять ваш вклад, и после подписания CLA вы становитесь почётным автором этого проекта. Для активных участников даже возможно присоединение к нашей основной команде и получение прав на объединение Pull Request.

Рекомендации

Чтобы ускорить процесс объединения PR, у нас есть несколько рекомендаций, которые могут быть полезны:

1. Создание ветки: рекомендуется использовать новую ветку для разработки, а ветку master рекомендуется поддерживать в соответствии с MOSN upstream.
2. Описание цели PR: если есть соответствующая обсуждаемая проблема, можно сослаться на неё. Если проблемы нет, необходимо чётко описать цель PR, например, исправление ошибки. Если изменения значительные, лучше предоставить подробное описание изменений.
3. Внесение новых коммитов для обработки отзывов: после получения отзывов на PR рекомендуется вносить новые коммиты вместо добавления их к исходным, чтобы облегчить просмотр рецензентом новых изменений.
4. Стремление к небольшим PR: несвязанные изменения лучше размещать в разных PR, что облегчает быстрый обзор и объединение.
5. Избегание принудительного push: поскольку принудительный push изменяет историю исходного кода, это затрудняет понимание процесса обзора другими людьми. Исключением является необходимость перебазирования при конфликте с master, после чего возможен только принудительный push.

Журнал коммитов

Рекомендуется начинать журнал коммитов с одного слова, например:

• feature: реализация новой функции или особенности;
• change: изменение без обратной совместимости;
• refactor: перестройка кода;
• bugfix: исправление ошибок;
• optimize: связанные с оптимизацией производительности изменения;
• doc: изменения в документации, включая комментарии;
• tests: связанные с тестовыми примерами изменения;
• style: корректировка стиля кода;
• sample: связанные с примерами изменения;
• chore: небольшие изменения, не затрагивающие основную логику.

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

bugfix: при преобразовании фильтра прослушивания из istio LDS получено неправильное имя файла CACert, из-за чего mosn может не прослушивать успешно.

Если описание сложное и не помещается в одно предложение, можно использовать несколько строк. Журнал коммитов не должен быть слишком длинным.

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

Соглашения по коду

Следующие требования к Pull Request не являются обязательными, но могут помочь вам при отправке PR:

1. Формат кода:
   • Командная строка: запустите goimports -w yourfile.go или golint yourfile.go, чтобы отформатировать код.
   • IDE: используйте такие IDE, как Goland, перейдите на страницу Go->imports и выберите «Group stdlib imports» — «Move all stdlib imports in a single group» — «Move all imports in a single declaration».
   • Во время выполнения CI-тестов будет проверяться формат кода, поэтому убедитесь, что вы отформатировали код перед отправкой.
2. Наличие документации: все новые файлы .go должны иметь простые комментарии doc, содержащие как минимум один тег author с вашим именем и предпочтительно хотя бы один абзац о назначении класса.
3. Добавление заголовков лицензий: добавьте заголовки лицензий Apache Software Foundation ко всем новым файлам .go (можно скопировать из существующих файлов проекта).
4. Указание авторства: укажите себя как автора всех изменённых вами файлов .go.
5. Документация: добавьте документацию.
6. Тестирование: проведение некоторых модульных тестов также будет полезным.
7. Покрытие кода: убедитесь, что покрытие кода не снижается.
8. Следование правилам Gitflow: рассматривайте PR как часть рабочего процесса Gitflow и следуйте правилам Pull Request.

Соглашение об именовании версий

Версии MOSN состоят из трёх цифр в формате x.x.x, где первая цифра учитывает совместимость, вторая — новые функции и улучшения, а третья — исправления ошибок.

Стратегия проверки кода участниками

При проверке кода участниками проекта рекомендуется следовать следующей стратегии:

1. Проверить соответствие PR соответствующей проблеме.
2. Проверить обоснованность решения.
3. Проверить результаты UT и Benchmark.
4. Обратить внимание на код, изменяющий структуру, использование глобальных переменных, особые случаи и обработку параллелизма.

Во время слияния:

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