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

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

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

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

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

1. Создание ветки: рекомендуется использовать новую ветку для разработки, а ветку master рекомендуется поддерживать в соответствии с изменениями в MOSN.

2. Описание цели PR: если есть соответствующая обсуждаемая проблема, можно сослаться на неё. Если проблемы нет, необходимо чётко описать цель PR, например, исправление ошибки. Если изменения значительные, лучше предоставить подробное описание изменений.

3. Внесение новых коммитов для обработки замечаний по обзору: после получения замечаний по PR рекомендуется вносить новые коммиты вместо добавления их к исходному коммиту, чтобы облегчить просмотр новых изменений рецензентом.

4. Стремление к небольшим PR: несвязанные изменения лучше размещать в разных PR, что облегчает быстрый обзор и объединение.

5. Избегание принудительного push: поскольку после принудительного push замечания по обзору не соответствуют исходной записи кода, это затрудняет понимание процесса обзора другими людьми. Исключение составляют случаи, когда требуется перебазирование для разрешения конфликтов с master, после чего возможен только принудительный push.

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

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

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

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

bugfix: got the wrong CACert filename when converting the listen filter from istio LDS, mosn may not listen success then.

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

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

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

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

1. Формат кода:

   • командная строка: запустите goimports -w yourfile.go или golint yourfile.go, чтобы отформатировать код;
   • IDE: используйте, например, Goland IDE, перейдите на страницу 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 не используются, предпочтительнее их редактировать и настраивать.