Внесение изменений в код

Этот раздел предназначен для основной команды Wagtail или для всех, кто интересуется процессом внесения изменений в код Wagtail.

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

Большинство вкладов в код осуществляются в виде запросов на вытягивание из Github. Запросы на вытягивание не должны быть объединены из Github, за исключением небольших исправлений документации, которые могут быть объединены с опцией «Сжатие и слияние». Вместо этого код должен быть выгружен участником локально, изменения проанализированы и перебазированы, CHANGELOG.txt и примечания к выпуску обновлены, а затем код должен быть отправлен на ветку main. Более подробная информация о данном процессе приведена ниже.

Выгрузка кода локально

Если код был представлен в виде запроса на вытягивание, вы должны получить изменения и выгрузить их в свой репозиторий Wagtail. Простой способ сделать это – добавить следующий git псевдоним в ваш ~/.gitconfig (предполагая, что upstream это wagtail/wagtail):

[alias]
    pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"

Теперь вы можете выгрузить запрос на вытягивание номер xxxx, выполнив команду git pr xxxx.

Перебазирование на main

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

Вы можете исправить любые мелкие ошибки в коммитах, такие как опечатки и форматирование, как часть перебазирования. git rebase --interactive – отличный инструмент для этой задачи.

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

$ # Get the latest commits from Wagtail
$ git fetch upstream
$ git checkout main
$ git merge --ff-only upstream/main
$ # Rebase this pull request on to main
$ git checkout pr/xxxx
$ git rebase main
$ # Update main to this commit
$ git checkout main
$ git merge --ff-only pr/xxxx

Обновление CHANGELOG.txt и примечаний к выпуску

Каждое значительное изменение в Wagtail должно быть отражено в CHANGELOG.txt, а также в примечаниях к выпуску текущей версии.

CHANGELOG.txt содержит краткое описание каждой новой функции, рефакторинга или исправления ошибок в каждом выпуске. Каждое описание должно занимать одну строку. Исправления ошибок должны быть сгруппированы в конце списка для каждого выпуска и начинаться с «Fix:». Имя участника должно быть добавлено в конце описания в скобках. Например:

* Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)

Примечания к каждому выпуску содержат более подробное описание каждого изменения. Также должны быть включены примечания о совместимости с предыдущими версиями. Крупные новые функции или изменения должны иметь собственный раздел, а более мелкие изменения и исправления ошибок должны быть сгруппированы в свой собственный раздел. Для примеров обратитесь к предыдущим примечаниям к выпуску. Примечания к выпуску каждой версии находятся в docs/releases/x.x.x.rst.

Если участник новый и это его первый вклад в Wagtail, его следует добавить в список CONTRIBUTORS.rst. Участники добавляются в хронологическом порядке, начиная с новых участников внизу списка. Используйте их предпочитаемое имя. Обычно имя участника можно найти на его странице профиля Github. В случае сомнений или если имя не указано на профиле, спросите у него, как он хотел бы, чтобы его называли.

Если объединяемые изменения достаточно небольшие для создания одного коммита, внесите в этот коммит дополнения к CHANGELOG.txt, примечания к выпуску и список участников:

$ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
$ git commit --amend --no-edit

Если изменения не помещаются в один коммит, создайте новый коммит с обновлёнными CHANGELOG.txt, примечаниями к выпуску и списком участников. Сообщение коммита должно гласить Release notes for #xxxx:

$ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
$ git commit -m 'Release notes for #xxxx'

Отправить на main

Теперь изменения готовы к отправке на main.

$ # Check that everything looks OK
$ git log upstream/main..main --oneline
$ git push --dry-run upstream main
$ # Push the commits!
$ git push upstream main
$ git branch -d pr/xxxx

Если вы допустили ошибку

Это нормально! Все допускают ошибки. Если вы обнаружили, что недавние объединённые изменения оказывают негативное влияние, создайте новый запрос на вытягивание с отката изменений и объедините его без ожидания проверки. Данный запрос на вытягивание послужит дополнительной документацией к изменениям и пройдёт тесты CI.

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

Пользователи Github с правами записи на wagtail/wagtail (члены ядра) могут добавить коммиты к ветке запроса на вытягивание участника.

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

$ git clone git@github.com:wagtail/wagtail.git
$ cd wagtail
$ git remote add johndoe git@github.com:johndoe/wagtail.git
$ git fetch johndoe foo
$ git checkout johndoe/foo
# Make changes
# Commit changes
$ git push johndoe HEAD:foo