Код фиксации ¶

Этот раздел адресован коммиттерам и всем, кто интересуется тем, как код попадает в Django. Если вы член сообщества, который хочет внести свой код в Django, посмотрите вместо этого Работа с Git и GitHub .

Обработка запросов на вытягивание

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

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

Возможно, вы захотите, чтобы Дженкинс протестировал запрос на перенос с помощью одного из построителей запросов на перенос, который не запускается автоматически, например Oracle или Selenium. См. Инструкции на вики-странице Jenkins .

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

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

Добавьте его ~/.gitconfig, и набор , upstreamчтобы быть django/django. Затем вы можете запустить для проверки соответствующий запрос на перенос.git pr ####

На этом этапе вы можете работать над кодом. Используйте и, чтобы убедиться, что коммиты имеют ожидаемый уровень качества. Когда вы будете готовы:git rebase -igit commit --amend

$ # Pull in the latest changes from main.
$ git checkout main
$ git pull upstream main
$ # Rebase the pull request on main.
$ git checkout pr/####
$ git rebase main
$ git checkout main
$ # Merge the work as "fast-forward" to main to avoid a merge commit.
$ # (in practice, you can omit "--ff-only" since you just rebased)
$ git merge --ff-only pr/XXXX
$ # If you're not sure if you did things correctly, check that only the
$ # changes you expect will be pushed to upstream.
$ git push --dry-run upstream main
$ # Push!
$ git push upstream main
$ # Delete the pull request branch.
$ git branch -d pr/xxxx
...\> REM Pull in the latest changes from main.
...\> git checkout main
...\> git pull upstream main
...\> REM Rebase the pull request on main.
...\> git checkout pr/####
...\> git rebase main
...\> git checkout main
...\> REM Merge the work as "fast-forward" to main to avoid a merge commit.
...\> REM (in practice, you can omit "--ff-only" since you just rebased)
...\> git merge --ff-only pr/XXXX
...\> REM If you're not sure if you did things correctly, check that only the
...\> REM changes you expect will be pushed to upstream.
...\> git push --dry-run upstream main
...\> REM Push!
...\> git push upstream main
...\> REM Delete the pull request branch.
...\> git branch -d pr/xxxx

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

Если пул-реквест не нужно объединять как несколько коммитов, вы можете использовать кнопку GitHub «Сжать и объединить» на веб-сайте. При необходимости отредактируйте сообщение фиксации, чтобы оно соответствовало рекомендациям, и удалите номер запроса на вытягивание, который автоматически добавляется в первую строку сообщения.

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

  • Если патч содержит двусторонние коммиты, перепишите их в одну. Например, если фиксация добавляет код, а вторая фиксация исправляет стилистические проблемы, появившиеся в первой фиксации, эти коммиты должны быть раздавлены перед объединением.
  • Разделяйте изменения в разных коммитах с помощью логической группировки: если вы выполняете стилистическую очистку одновременно с другими изменениями файла, разделение изменений на два разных коммита упростит просмотр истории.
  • Остерегайтесь слияния вышестоящих веток в запросах на вытягивание.
  • Тесты должны проходить, а документация должна строиться после каждой фиксации. Ни тесты, ни документация не должны выдавать предупреждений.
  • Тривиальные и небольшие патчи обычно лучше делать за один коммит. Средняя и большая работа может быть разделена на несколько коммитов, если это имеет смысл.

Практичность важнее чистоты, поэтому каждый коммиттер сам решает, сколько искажений истории нужно сделать для запроса на вытягивание. Основные моменты - это вовлечение сообщества, выполнение работы и наличие удобной истории коммитов.

Рекомендации по фиксации ¶

Кроме того, при коммите кода в репозиторий Git Django следуйте следующим рекомендациям:

  • Никогда не изменяйте опубликованную историю django/djangoветвей принудительным нажатием. Если вам это абсолютно необходимо (например, из соображений безопасности), сначала обсудите ситуацию с командой.

  • Для любых средних и больших изменений, где «от среднего к большому», по вашему мнению, пожалуйста, сообщите об этом в списке рассылки django-developers, прежде чем вносить изменения.

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

  • Пишите подробные сообщения о фиксации в прошедшем, а не в настоящем времени.

    • Хорошо: «Исправлена ​​ошибка Unicode в RSS API».
    • Плохо: «Исправляет ошибку Unicode в RSS API».
    • Плохо: «Исправление ошибки Unicode в RSS API».

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

    Fixed #18307 -- Added git workflow guidelines.
    
    Refactored the Django's documentation to remove mentions of SVN
    specific tasks. Added guidelines of how to use Git, GitHub, and
    how to use pull request together with Trac instead.
    

    Отметьте участников в сообщении о фиксации: «Спасибо А за отчет и Б за проверку». При необходимости используйте git's Co-Authored-By .

  • Для коммитов в ветку добавьте к сообщению фиксации имя ветки. Например: «[1.4.x] Исправлено #xxxxx - Добавлена ​​поддержка чтения мыслей».

  • Limit фиксирует самые мелкие изменения, которые имеют смысл. Это означает, что используйте частые небольшие коммиты, а не нечастые большие. Например, если для реализации функции X требуется небольшое изменение в библиотеке Y, сначала зафиксируйте изменение в библиотеке Y, а затем зафиксируйте функцию X в отдельной фиксации. Это идет долгий путь , помогая всем следовать изменениям.

  • Отделяйте исправления ошибок от изменений функций. Исправления ошибок, возможно, потребуется перенести в стабильную ветку в соответствии с поддерживаемыми версиями .

  • Если ваша фиксация закрывает тикет в трекере тикетов Django , начните ваше сообщение фиксации с текста «Fixed #xxxxx», где «xxxxx» - номер тикета, исправляемого вашим коммитом. Пример: «Исправлено № 123 - Добавлена ​​функция свистящего звука». Мы настроили Trac таким образом, что любое сообщение фиксации в этом формате автоматически закрывает указанный тикет и публикует к нему комментарий с полным сообщением фиксации.

    Для любопытных мы используем для этого плагин Trac .

Примечание

Обратите внимание, что интеграция Trac ничего не знает о запросах на вытягивание. Поэтому, если вы попытаетесь закрыть запрос на перенос с фразой «закрывает # 400» в сообщении о фиксации, GitHub закроет запрос на перенос, но плагин Trac также закроет тот же пронумерованный билет в Trac.

  • Если ваша фиксация ссылается на тикет в трекере тикетов Django, но не закрывает тикет, включите фразу «Refs #xxxxx», где «xxxxx» - это номер тикета, на который ссылается ваш коммит. Это автоматически добавит комментарий к соответствующему запросу.

  • Напишите сообщения фиксации для backports, используя этот шаблон:

    [<Django version>] Fixed <ticket> -- <description>
    
    Backport of <revision> from <branch>.
    

    Например:

    [1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
    
    Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
    

    В вики есть сценарий для автоматизации этого.

    Если фиксация исправляет регресс, включите это в сообщение фиксации:

    Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
    

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

Откат коммитов

Никто не идеален; будут совершаться ошибки.

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

При обнаружении ошибочной фиксации следуйте этим рекомендациям:

  • Если возможно, попросите первоначального автора отменить свою фиксацию.
  • Не отменяйте изменения, внесенные другим автором, без разрешения первоначального автора.
  • Используйте git revert - это сделает обратную фиксацию, но исходная фиксация все равно будет частью истории фиксации.
  • Если с исходным автором невозможно связаться (в течение разумного промежутка времени - день или около того) и проблема серьезная - сбой, серьезные сбои тестов и т. Д. - то попросите возражения в списке рассылки django-developers, а затем вернуться, если их нет.
  • Если проблема небольшая (скажем, фиксация функции после ее зависания), подождите.
  • Если есть разногласия между коммиттером и будущим ревертером, попробуйте уладить его в списке рассылки django-developers . Если соглашение не может быть достигнуто, его следует поставить на голосование.
  • Если фиксация привела к подтвержденной обнаруженной уязвимости безопасности, фиксация может быть немедленно отменена без разрешения кого-либо.
  • Сопровождающий ветки релиза может отказаться от коммитов в ветку релиза без разрешения, если фиксация прерывает ветвь релиза.
  • Если вы по ошибке нажали ветку темы django/django, удалите ее. Например, если вы сделали: , сделать обратный толчок: .git push upstream feature_antigravitygit push upstream :feature_antigravity

Copyright ©2021 All rights reserved