Внесение вклада в проект Dragonfly

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

Темы

• Сообщение о проблемах безопасности
• Сообщение о общих проблемах
• Вклад в код и документацию
• Участие в помощи любому аспекту проекта
• Присоединение к Dragonfly как члену команды

Сообщение о проблемах безопасности

Проблемы безопасности всегда рассматриваются серьезно. По нашей обычной политике, мы не рекомендуем никому распространять информацию о проблемах безопасности. Если вы нашли проблему безопасности в Dragonfly, пожалуйста, не обсуждайте её публично и даже не открывайте публичный запрос. Вместо этого мы просим вас отправить нам закрытое сообщение на адрес dragonfly-dev@service.alibaba.com.

Сообщение о общих проблемах

Откровенно говоря, мы считаем каждого пользователя Dragonfly ценным вкладчиком. После использования Dragonfly у вас могут возникнуть какие-либо отзывы о проекте. Вы можете открыть запрос через НОВЫЙ ЗАПРОС.Так как мы сотрудничаем над проектом Dragonfly распределённым образом, мы ценим полностью заполненные, добросовестно объяснённые, ясно указанные запросы. Чтобы сделать общение более эффективным, мы просим всех проверить наличие вашего запроса среди существующих запросов. Если вы найдете его уже существующим, пожалуйста, добавьте ваши детали в комментариях под существующим запросом вместо создания нового.

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

Вы можете открыть запрос в следующих случаях:

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

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

Внесение изменений в код и документациюКаждое действие, направленное на улучшение проекта Dragonfly, приветствуется. На GitHub любое улучшение для Dragonfly может быть выполнено через PR (pull request).

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

На самом деле невозможно полностью перечислить все возможные улучшения. Просто помните одно правило:

НАМ ОЧЕНЬ ЖЕЛАТЕЛЬНЫ ЛЮБЫЕ ВАШИ PR.

Поскольку вы готовы улучшить Dragonfly с помощью PR, мы рекомендуем вам ознакомиться с правилами PR здесь.

• Подготовка рабочего пространства
• Определение ветки
• Правила коммита
• Описание PR
• Среда разработки
• Управление зависимостями Go

Подготовка рабочего пространстваДля того чтобы отправить pull request (PR), мы предполагаем, что у вас есть учетная запись GitHub. Выполните подготовку следующими шагами:

1. Создайте fork проекта Dragonfly в вашем репозитории. Для этого нажмите кнопку Fork справа на странице dragonflyoss/Dragonfly. После этого вы окажетесь в своем репозитории по адресу https://github.com/<ваш-пользователь>/Dragonfly, где <ваш-пользователь> — ваш логин на GitHub.

2. Клонируйте свой репозиторий на локальную машину. Используйте команду git clone https://github.com/<ваш-пользователь>/Dragonfly.git для клонирования репозитория на вашей локальной машине. Теперь вы можете создать новые ветки для выполнения необходимых изменений.

3. Установите удаленный репозиторий upstream на https://github.com/dragonflyoss/Dragonfly.git с помощью следующих двух команд:

   git remote add upstream https://github.com/dragonflyoss/Dragonfly.git
   git remote set-url --push upstream no-pushing

   С этими настройками удаленного репозитория вы можете проверить конфигурацию своего репозитория так:

   $ git remote -v
   origin     https://github.com/<ваш-пользователь>/Dragonfly.git (fetch)
   origin     https://github.com/<ваш-пользователь>/Dragonfly.git (push)
   upstream   https://github.com/dragonflyoss/Dragonfly.git (fetch)
   upstream   no-pushing (push)

4. Создайте ветку для добавления новой функции или исправления проблем.

Обновление локального рабочего каталога:```bash cd Dragonfly git fetch upstream git checkout master git rebase upstream/master

Создание новой ветки:

```bash
git checkout -b <новая_ветка>

Сделайте любые изменения в новая_ветка, затем скомпилируйте и протестируйте свои коды.

Определение ветки

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

Как участник, помните еще раз, что каждое вкладывание через запрос на слияние предназначено для ветки master. В проекте Dragonfly есть несколько других веток, которые мы обычно называем rc (release candidate) ветками, ветками выпуска и ветками обратной совместимости.

Перед официальным выпуском версии, мы будем использовать ветку rc (release candidate). В этой ветке мы будем тестировать больше, чем в ветке master.

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

При обратной совместимости некоторых исправлений к уже выпущенной версии, мы будем использовать ветки обратной совместимости. После обратной совместимости, эффекты обратной совместимости будут отражены в номере PATCH в MAJOR.MINOR.PATCH SemVer.

Правила коммита

Действительно, в Dragonfly мы серьезно относимся к двум правилам при коммите:* Сообщение коммита

• Контент коммита

Сообщение коммита

Сообщение коммита может помочь рецензентам лучше понять цель отправленного PR. Это также может ускорить процедуру рецензирования кода. Мы рекомендуем участникам использовать ЯСНОЕ сообщение коммита вместо неопределенного сообщения. В общем, мы пропагируем следующие типы сообщений коммита:

• docs: добавить документацию о установке хранилища.

• feature: сделать вывод результата в отсортированном порядке.

• bugfix: исправить панику при вводе null параметра.

• style: форматировать стиль кода файла Constants.java.

• refactor: упростить для повышения читабельности кода.

• test: добавить тестовый случай для функции InsertIntoArray.

• chore: интегрировать Travis-CI. Это тип обслуживания.

• другие читаемые и явные способы выражения. С другой стороны, мы не рекомендуем вкладчикам отправлять сообщения о коммите следующего типа:

• фикс бага

• обновление

• добавление документации

Контент коммитаСодержание коммита должно включать все изменения, внесённые в одном коммите. Лучше всего объединять в один коммит те изменения, которые позволяют рецензенту полностью проверить его без необходимости обращения к другим коммитам. Другими словами, содержимое одного коммита должно проходить CI, чтобы избежать путаницы с кодом. Кратко говоря, существуют два простых правила, которые следует запомнить:* избегайте очень больших изменений в одном коммите;

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

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

Описание Pull Request

Pull Request — единственный способ вносить изменения в файлы проекта Dragonfly. Чтобы помочь рецензентам лучше понять вашу цель, описание Pull Request не должно быть слишком подробным. Мы рекомендуем вкладчикам использовать шаблон Pull Request для завершения запроса на вытягивание.

Разработка окружения

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

• golang : v1.12.10
• swagger : 0.19.0
• markdownlint : v0.5.0
• misspell : последняя
• shellcheck : последняя
• docker: последняя

Когда вы работаете над проектом Dragonfly в локальной среде, вам следует использовать подкоманды Makefile для проверки и сборки последней версии Dragonfly. Для удобства разработчиков мы используем Docker для сборки Dragonfly. Это помогает избежать проблем с разработочной средой.

Управление зависимостями Go

Проект Dragonfly использует Go модули для управления зависимостями на внешние пакеты. Это требует наличия рабочей среды Go с установленной версией 1.12 или выше.Чтобы добавить или обновить новую зависимость, используйте команду go get:

# Выберите последний отмеченный выпуск.
go get example.com/some/module/pkg

# Выберите конкретную версию.
go get example.com/some/module/pkg@vX.Y.Z

Очистите файлы go.mod и go.sum:

make go-mod-tidy

Вы должны зафиксировать изменения в файлах go.mod и go.sum перед отправкой Pull Request.```bash git add go.mod go.sum git commit

## Участвовать в помощи любым способом

Мы выбрали GitHub как основное место для сотрудничества над Dragonfly. Так что последние обновления Dragonfly всегда доступны здесь. Хотя внесение изменений через Pull Request явный способ помочь, мы все равно призываем использовать любой другой подход.

* отвечайте на вопросы других, если можете;
* помогите решить проблемы других пользователей;
* помогите проверять концепции других Pull Requests;
* помогите проверять код других в Pull Requests;
* обсуждайте Dragonfly, чтобы сделать вещи более понятными;
* продвигайте технологию Dragonfly за пределами GitHub;
* пишите статьи о Dragonfly и так далее.

Кратко говоря, **каждая возможность помощи — это включение в команду**.

## Присоединиться к команде Dragonfly

Также приветствуется присоединение к команде Dragonfly, если вы готовы постоянно участвовать в сообществе Dragonfly и оставаться активным.

### Требования* Ознакомились с [правилами участия в проекте Dragonfly](CONTRIBUTING.md);
* Ознакомились с [кодексом поведения Contributor Covenant](CODE_OF_CONDUCT.md);
* Подали несколько Pull Requests в сообщество;
* Быть активным в сообществе, что может включать, но не ограничивается следующими действиями:
  * Отправка или комментирование вопросов;
  * Внесение Pull Requests в сообщество;
  * Проверка Pull Requests в сообществе;### Как это сделать

Вы можете это сделать одним из двух способов:

* Подайте Pull Request в репозиторий [dragonflyoss/Dragonfly](https://github.com/dragonflyoss/Dragonfly);
* Обратитесь к [поддержке сообщества](MAINTAINERS.md) офлайн;