Фиксация кода ¶

Управление запросами на участие ¶

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

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

Может быть желательно, чтобы Дженкинс протестировал запрос на участие, используя один из конструкторов, которые не запускаются автоматически, например Oracle или Selenium. См. Дополнительную информацию на странице Jenkins Wiki .

Если вам приходится часто получать запросы на участие локально, вам пригодится этот псевдоним 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 -i git commit --amend

$ # Pull in the latest changes from master.
$ git checkout master
$ git pull upstream master
$ # Rebase the pull request on master.
$ git checkout pr/####
$ git rebase master
$ git checkout master
$ # Merge the work as "fast-forward" to master 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 master
$ # Push!
$ git push upstream master
$ # Delete the pull request branch.
$ git branch -d pr/xxxx

...\> REM Pull in the latest changes from master.
...\> git checkout master
...\> git pull upstream master
...\> REM Rebase the pull request on master.
...\> git checkout pr/####
...\> git rebase master
...\> git checkout master
...\> REM Merge the work as "fast-forward" to master 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 master
...\> REM Push!
...\> git push upstream master
...\> REM Delete the pull request branch.
...\> git branch -d pr/xxxx

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

Если запрос на участие не должен быть объединен с несколькими разными коммитами, можно использовать кнопку «Сжать и объединить» на веб-сайте. Измените сообщение фиксации, чтобы оно соответствовало: ref: Guidelines <committing-guidelines> `и удалите номер запроса на участие, который автоматически добавляется в первую строку сообщения.

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

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

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

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

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

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

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

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

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

  • Просто: «Исправлена ​​ошибка Unicode в RSS API. "
  • False: «Исправлена ​​ошибка 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 Co-Authored-By .

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

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

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

• Если фиксация закрывает билет в системе отслеживания Django, начните сообщение фиксации с текста «Fixed #xxxxx», где «xxxxx» - номер билета, разрешенного фиксацией. Пример: «Исправлено # 123 - Добавлена ​​функция whizbang. ». Мы адаптировали 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 master.
  

  В вики есть сценарий < https://code.djangoproject.com/wiki/CommitterTips#AutomatingBackports > `_ для автоматизации этого.

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

  Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
  

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

Отмена коммитов ¶

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

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

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

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