Внесение вклада в код

Добро пожаловать в проект MaxKey. Мы ценим ваш вклад и благодарим вас за участие. Этот документ описывает наш рабочий процесс и процедуры, а также может служить руководством для разработчиков.

Процесс работы

Различные модели, используемые при разработке MaxKey, доступны для скачивания по этой ссылке скачать.

Создание форка

Для отправки запроса на слияние используется модель Pull Request. Прямое выполнение команды push запрещено. Все изменения должны проходить через рецензию. Первым шагом является создание форка MaxKey "Кнопка Fork".
Переходим на страницу MaxKey на GitHub, затем нажимаем кнопку Fork, чтобы создать свой личный репозиторий, например https://github.com/ваш\_пользователь/MaxKey.

Клонирование (clone)

Клонируем удаленный репозиторий на локальную машину:

➜  git clone https://github.com/ваш\_пользователь/MaxKey
➜  cd MaxKey

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

MaxKey использует модель ветвлений Git Flow для разработки, тестирования, выпуска и обслуживания.

Все изменения функциональности и исправлений ошибок следует выполнять в новой ветке, обычно созданной от ветки develop.

Создаем и переходим в новую ветку с помощью команды git checkout -b.

➜  git checkout -b моя\_крутая\_ветка

Перед выполнением команды checkout важно очистить текущую ветку, чтобы избежать перемещения неотслеживаемых файлов в новую ветку. Это можно проверить с помощью команды git status.

Использование `pre-commit` хуков

Разработчики MaxKey используют инструмент pre-commit для управления предварительными хуками Git. Эти хуки автоматически выполняют проверки перед каждым коммитом (например, наличие одного конца строки в каждом файле, отсутствие больших файлов в Git и т.д.).

Прежде чем сделать коммит, необходимо выполнить проверку pre-commit. Это часть юнит-тестов, и если проверка не пройдет, коммит будет отклонен.

pip install pre-commit
pre-commit -v -a

Начало разработки

В этом примере мы удалили одну строку из файла README.md и создали новый файл.

Проверяем состояние текущего каталога с помощью команды git status, которая покажет изменения в каталоге, а также позволяет просмотреть конкретные изменения в файлах с помощью команды git diff.

➜  git status
На ветке test
Изменения, не предназначенные для коммита:
  (используйте "git add <файл>..." для обновления того, что будет коммитировано)
  (используйте "git checkout -- <файл>..." для отмены изменений в рабочей директории)

  изменён:   README.md

Неотслеживаемые файлы:
  (используйте "git add <файл>..." для включения в то, что будет коммитировано)

  test

Ничего не добавлено к коммиту, но есть неотслеживаемые файлы (используйте "git add", чтобы начать отслеживание)

Сборка

Установите переменные окружения gradleSetEnv.bat

set JAVA_HOME=D:\JavaIDE\jdk1.8.0_91
set GRADLE_HOME=D:\JavaIDE\gradle-5.4.1

Запустите сборку gradleBuildRelease.bat

Результат сборки Путь к сборке

MaxKey/build/maxkey-jars

Путь к зависимостям

MaxKey/build/maxkey-depjars

Дополнительные настройки разработки см. в разделе https://maxkey.top/ru/development.html

Коммит

Отменяем изменения в README.md и добавляем новый файл test.

➜  git checkout -- README.md
➜  git status
На ветке test
Неотслеживаемые файлы:
  (используйте "git add <файл>..." для включения в то, что будет коммитировано)

  test

Нечего добавить к коммиту, но есть неотслеживаемые файлы (используйте "git add", чтобы начать отслеживание)
➜  git add test

Каждый коммит требует сообщения о коммите, которое должно объяснять, какие изменения были сделаны. Это можно сделать с помощью команды git commit.

▶ pre-commit run -a -v
[remove-crlf] Удалитель символов CRLF........................................Прошел
[remove-tabs] Удалитель табуляций............................................Прошел
[check-added-large-files] Проверка добавленных больших файлов................Прошел
[check-merge-conflict] Проверка конфликтов слияния............................Прошел
[check-symlinks] Проверка сломанных символьных ссылок........................Прошел
[detect-private-key] Обнаружение закрытого ключа.............................Прошел
[end-of-file-fixer] Корректор концов файлов..................................Прошел
[trailing-whitespace] Удаление пробелов в конце строки........................Прошел
[copyright] авторское право..................................................Прошло
[clang-format] clang-format...................................................Прошло

Сохранение актуальности локального репозитория

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

Сначала используем команду git remote для просмотра имени текущего удаленного репозитория.

➜  git remote
origin
➜  git remote -v
origin    https://github.com/USERNAME/MaxKey (fetch)
origin    https://github.com/USERNAME/MaxKey (push)

Здесь origin — это имя нашего клонированного удаленного репозитория, то есть репозитория пользователя USERNAME. Добавляем оригинальный репозиторий MaxKey как удаленный репозиторий, называем его upstream.

➜  git remote add upstream https://github.com/MaxKeyTop/MaxKey
➜  git remote
origin
upstream

Получаем последние изменения из upstream и применяем их к текущей ветке.

➜  git fetch upstream
➜  git pull upstream develop

Отправка на удаленный репозиторий

Отправляем изменения на GitHub, то есть на https://github.com/USERNAME/MaxKey.

# Отправляем изменения на удаленный репозиторий origin в ветку my-cool-stuff
➜  git push origin my-cool-stuff

Создание проблемы и завершение запроса на слияние

Создаем проблему (issue) и записываем её номер.

Переходим на ветку, которую создали, затем нажимаем кнопку New pull request.

В описании запроса на слияние указываем resolve #issue_number, чтобы после успешного слияния проблема была автоматически закрыта.

Подробнее см. в разделе https://help.github.com/articles/closing-issues-via-commit-messages/

Рецензия

Удаление удаленной ветки

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

Это можно сделать с помощью команды git push origin :ветка.```bash ➜ git push origin :my-cool-stuff




## Удаление локальной ветки

Наконец, удаляем локальную ветку.

```bash
# Переходим на ветку develop
➜  git checkout develop 

# Удаляем ветку my-cool-stuff
➜  git branch -d my-cool-stuff

Таким образом, мы завершили процесс внесения вклада в код.

Определённые соглашения при коммите

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

Убедитесь, что все юнит-тесты проходят успешно. Если нет, это говорит о том, что ваши изменения могут содержать ошибки, и рецензенты скорее всего не будут рассматривать этот коммит.
Перед отправкой запроса на слияние:
- Обратите внимание на количество коммитов:
  - Причина: Если вы изменили один файл, но сделали несколько коммитов, каждый из которых содержит минимальные изменения, это усложняет процесс рецензирования. Рецензентам придётся просмотреть каждый коммит, чтобы понять, какие именно изменения были внесены.
  - Совет: Старайтесь делать минимальное количество коммитов. Вы можете использовать команду git commit --amend для добавления изменений к предыдущему коммиту. Если вы уже отправили несколько коммитов на удалённый репозиторий, вы можете скомбинировать их с помощью команды git rebase.
- Обратите внимание на название каждого коммита: оно должно точно отражать содержание коммита.
Если вы решили проблему, связанную с определённым issue, укажите это в первом комментарии вашего запроса на слияние, добавив fix #issue_number. После успешного слияния это позволит автоматически закрыть соответствующий issue. Возможные ключевые слова включают close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. Подробнее см. в разделе https://help.github.com/articles/closing-issues-via-commit-messages

Кроме того, при ответах на отзывы рецензентов следует придерживаться следующих правил:

Ответьте на каждый отзыв рецензента (это базовая вежливость в открытых проектах):
- Если вы согласны с отзывом и применили его рекомендации, просто отметьте это как "Done".
- Если вы не согласны с отзывом, предоставьте свои контраргументы.
Если у вас много отзывов:
- Предложите общую картину ваших изменений.
- Используйте команду start a review для ответа, вместо простого ответа. Это поможет избежать множества электронных писем.

OSCHINA-MIRROR/dromara-MaxKey

Внесение вклада в код

Процесс работы

Создание форка

Клонирование (clone)

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

Использование `pre-commit` хуков

Начало разработки

Сборка

Коммит

Сохранение актуальности локального репозитория

Отправка на удаленный репозиторий

Создание проблемы и завершение запроса на слияние

Рецензия

Удаление удаленной ветки

Определённые соглашения при коммите

Опубликовать ( 0 )

Введение

Обновления (56)

Участники

Недавние действия

OSCHINA-MIRROR/dromara-MaxKey .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Внесение вклада в код

Процесс работы

Создание форка

Клонирование (clone)

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

Использование pre-commit хуков

Начало разработки

Сборка

Коммит

Сохранение актуальности локального репозитория

Отправка на удаленный репозиторий

Создание проблемы и завершение запроса на слияние

Рецензия

Удаление удаленной ветки

Определённые соглашения при коммите

Опубликовать ( 0 )

Введение

Обновления (56)

Участники

Недавние действия

OSCHINA-MIRROR/dromara-MaxKey

Использование `pre-commit` хуков