Отправка патчей ¶
Мы всегда благодарны за патчи к коду Django. Действительно, отчеты об ошибках с соответствующими исправлениями будут исправлены гораздо быстрее, чем отчеты без исправлений.
Исправления опечаток и тривиальные изменения документации ¶
Если вы исправляете действительно тривиальную проблему, например изменяете слово в документации, предпочтительный способ предоставить патч - использовать запросы на вытягивание GitHub без билета Trac.
См. Раздел Работа с Git и GitHub для получения дополнительных сведений о том, как использовать запросы на вытягивание.
«Получение» билетов ¶
В проекте с открытым исходным кодом с сотнями участников по всему миру важно эффективно управлять коммуникацией, чтобы работа не дублировалась, а участники могли быть максимально эффективными.
Следовательно, наша политика заключается в том, чтобы участники «заявляли» заявки, чтобы сообщить другим разработчикам, что над той или иной ошибкой или функцией работают.
Если вы определили вклад, который хотите внести, и можете его исправить (если судить по вашим способностям кодирования, знанию внутреннего устройства Django и доступности времени), заявите о нем, выполнив следующие действия:
- Войдите в систему, используя свою учетную запись GitHub, или создайте учетную запись в нашей системе билетов. Если у вас есть учетная запись, но вы забыли пароль, вы можете сбросить ее на странице сброса пароля .
- Если билет для этой проблемы еще не существует, создайте его в нашем трекере билетов .
- Если билет по этой проблеме уже существует, убедитесь, что никто его не забрал. Для этого посмотрите в разделе заявки «Принадлежит». Если он назначен «никому», то он доступен для востребования. В противном случае над этой заявкой может работать кто-то другой. Либо найдите другую ошибку / функцию, над которой нужно поработать, либо обратитесь к разработчику, работающему над тикетом, чтобы предложить свою помощь. Если билет был назначен на недели или месяцы без каких-либо действий, вероятно, безопасно переназначить его самому себе.
- Войдите в свою учетную запись, если вы еще этого не сделали, нажав «Вход в GitHub» или «Вход в DjangoProject» в левом верхнем углу страницы заявки.
- Получите билет, щелкнув переключатель «назначить себе» в разделе «Действие» в нижней части страницы, а затем нажмите «Отправить изменения».
Примечание
Фонд программного обеспечения Django требует, чтобы каждый, кто вносит в Django более чем простой патч, подписал и отправил лицензионное соглашение со спонсором, это гарантирует, что Django Software Foundation имеет четкую лицензию на все вклады, что позволяет получить четкую лицензию для всех пользователей.
Ответственность заявителей билетов ¶
После того, как вы забрали билет, вы обязаны работать над ним в разумные сроки. Если у вас нет времени над этим поработать, либо откажитесь от него, либо вообще не претендуйте!
Если в течение недели или двух нет никаких признаков прогресса по конкретному заявленному билету, другой разработчик может попросить вас отказаться от заявки на билет, чтобы он больше не был монополизирован, и кто-то другой мог потребовать его.
Если вы запросили билет, а кодирование занимает много времени (дни или недели), держите всех в курсе, публикуя комментарии к билету. Если вы не предоставляете регулярные обновления и не отвечаете на запрос отчета о проделанной работе, ваша заявка на билет может быть отозвана.
Как всегда, больше общения лучше, чем меньше общения!
Какие билеты следует запрашивать? ¶
В некоторых случаях процесс получения билетов является излишним.
В случае небольших изменений, таких как опечатки в документации или мелкие ошибки, исправление которых займет всего несколько минут, вам не нужно прыгать через обруч, требуя билетов. Отправьте патч напрямую, и все готово!
Это всегда приемлемо, имеет независимо от того , кто утверждал , что это или нет, представить патчи на билет , если вам посчастливилось иметь патч готов.
Стиль патча ¶
Убедитесь, что любой вклад, который вы делаете, соответствует как минимум следующим требованиям:
- Код, необходимый для исправления проблемы или добавления функции, является важной частью патча, но не единственной его частью. Хороший патч должен также включать регрессионный тест для проверки исправленного поведения и предотвращения повторного возникновения проблемы. Кроме того, если некоторые тикеты имеют отношение к написанному вами коду, укажите номера тикетов в некоторых комментариях к тесту, чтобы можно было легко отследить соответствующие обсуждения после того, как ваш патч будет зафиксирован, и тикеты будут закрыты.
- Если код, связанный с патчем, добавляет новую функцию или изменяет поведение существующей функции, патч также должен содержать документацию.
Когда вы считаете, что ваша работа готова к рассмотрению, отправьте запрос на перенос на GitHub . Пожалуйста, проверьте исправление самостоятельно, используя наш контрольный список для проверки исправлений .
Если по какой-то причине вы не можете отправить запрос на перенос, вы также можете использовать патчи в Trac. При использовании этого стиля следуйте этим рекомендациям.
- Отправьте исправления в формате, возвращенном командой.
git diff
- Прикрепите патчи к тикету в тикет-трекере , используя кнопку «прикрепить файл». Пожалуйста , не помещайте патч в описание или комментарий заявки, если это не однострочный патч.
- Назовите файл патча с
.diff
расширением; это позволит системе отслеживания билетов применить правильную подсветку синтаксиса, что весьма полезно.
Независимо от того, как вы отправляете свою работу, выполните следующие действия.
- Убедитесь, что ваш код соответствует требованиям нашего контрольного списка для проверки исправлений .
- Установите флажок «Имеет исправление» в заявке и убедитесь, что флажки «Требуется документация», «Требуются тесты» и «Исправление требует улучшения» не отмечены. В результате заявка появится в очереди «Исправления, требующие проверки» на панели инструментов разработки .
Нетривиальные патчи ¶
«Нетривиальный» патч - это нечто большее, чем исправление небольшой ошибки. Это патч, который вводит функциональность Django и принимает какое-то дизайнерское решение.
Если вы предоставляете нетривиальный патч, включите доказательства того, что альтернативы обсуждались на django-developers .
Если вы не уверены, следует ли считать ваш патч нетривиальным, спросите мнение в билете.
Прекращение поддержки функции ¶
Код в Django может быть устаревшим по нескольким причинам:
- Если функция была улучшена или изменена обратно несовместимым способом, старая функция или поведение будут считаться устаревшими.
- Иногда Django будет включать бэкпорт библиотеки Python, который не включен в версию Python, которую Django в настоящее время поддерживает. Когда Django больше не будет поддерживать старую версию Python, в которую не входит эта библиотека, в Django эта библиотека будет считаться устаревшей.
Как описано в политике устаревания , первый выпуск Django, в котором объявлена устаревшая функция ( A.B
), должен вызывать
RemovedInDjangoXXWarning
(где XX - версия Django, в которой функция будет удалена) при вызове устаревшей функции. Предположу , что мы имеем хорошее тестовое покрытие, эти предупреждения преобразуются к ошибкам при выполнении тестов с предупреждениями включено:
. Таким образом, при добавлении
вам необходимо устранить или отключить все предупреждения, генерируемые при запуске тестов.python -Wa runtests.py
RemovedInDjangoXXWarning
Первый шаг - отменить любое использование устаревшего поведения самим Django. Затем вы можете отключить предупреждения в тестах, которые фактически проверяют устаревшее поведение, используя ignore_warnings
декоратор, либо на уровне теста, либо на уровне класса:
В конкретном тесте:
from django.test import ignore_warnings from django.utils.deprecation import RemovedInDjangoXXWarning @ignore_warnings(category=RemovedInDjangoXXWarning) def test_foo(self): ...
Для всего тестового примера:
from django.test import ignore_warnings from django.utils.deprecation import RemovedInDjangoXXWarning @ignore_warnings(category=RemovedInDjangoXXWarning) class MyDeprecatedTests(unittest.TestCase): ...
Вы также можете добавить тест на предупреждение об устаревании:
from django.utils.deprecation import RemovedInDjangoXXWarning
def test_foo_deprecation_warning(self):
msg = 'Expected deprecation message'
with self.assertWarnsMessage(RemovedInDjangoXXWarning, msg):
# invoke deprecated behavior
Наконец, есть пара обновлений в документации Django:
- Если существующая функция задокументирована, пометьте ее как устаревшую в документации с помощью аннотации. Включите краткое описание и примечание о пути обновления, если применимо.
.. deprecated:: A.B
- Добавьте описание устаревшего поведения и, если применимо, путь обновления в примечания к текущему выпуску (
docs/releases/A.B.txt
) под заголовком «Функции, не рекомендуемые в AB». - Добавьте запись на временную шкалу устаревания (
docs/internals/deprecation.txt
) под соответствующей версией, описывающую, какой код будет удален.
Выполнив эти шаги, вы прекратите поддержку. В каждом выпуске функцииRemovedInDjangoXXWarning
удаляются все,
соответствующие новой версии.
Патчи JavaScript ¶
Для получения информации об исправлениях JavaScript см. Документацию по исправлениям JavaScript .
Контрольный список проверки исправлений ¶
Используйте этот контрольный список для просмотра запроса на вытягивание. Если вы просматриваете чужой запрос на перенос и он соответствует всем нижеприведенным критериям, установите для параметра «Этап сортировки» в соответствующем билете Trac значение «Готово к регистрации». Если вы оставили комментарии для улучшения запроса на вытягивание, отметьте соответствующие флажки в заявке Trac на основе результатов вашей проверки: «Исправление требует улучшения», «Требуется документация» и / или «Требуются тесты». Если позволяет время и интерес, коммиттеры проводят окончательную проверку билетов «Готовы к регистрации» и либо фиксируют исправление, либо возвращают его в состояние «Принято», если необходимо выполнить дальнейшие работы. Если вы хотите стать коммиттером, тщательная проверка исправлений - отличный способ заработать доверие.
Ищете патч для обзора? Ознакомьтесь с разделом «Исправления, требующие проверки» на панели инструментов разработки Django . Хотите, чтобы ваш патч был рассмотрен? Убедитесь, что флаги Trac в заявке установлены так, чтобы заявка появилась в этой очереди.
Документация ¶
- Документация создается без ошибок ( или
в Windows из каталога)?
make html
make.bat html
docs
- Соответствует ли документация рекомендациям по стилю написания документации Writing ?
- Есть ли орфографические ошибки ?
Ошибки ¶
- Существует ли подходящий регрессионный тест (тест должен завершиться неудачно до того, как будет применено исправление)?
- Если это ошибка, которая подходит для резервного копирования
в стабильную версию Django, есть ли в ней примечания к выпуску
docs/releases/A.B.C.txt
? Исправления ошибок, которые будут применены только к основной ветке, не нуждаются в примечаниях к выпуску.
Новые возможности ¶
- Существуют ли тесты для «отработки» всего нового кода?
- Есть примечание к выпуску
docs/releases/A.B.txt
? - Есть ли документация для функции и ее аннотированный соответственно с
или ?
.. versionadded:: A.B
.. versionchanged:: A.B
Прекращение поддержки функции ¶
См. Руководство по устаревшим функциям .
Все изменения кода ¶
- Соответствует ли стиль кодирования нашим рекомендациям? Есть ли
flake8
ошибки? Вы можете установить перехватчики перед фиксацией, чтобы автоматически отлавливать эти ошибки. - Если изменение каким-либо образом обратно несовместимо, есть ли примечание в примечаниях к выпуску (
docs/releases/A.B.txt
)? - Тестовый набор Django прошел?
Все билеты ¶
- Является ли запрос на вытягивание единственной сжатой фиксацией с сообщением, которое соответствует нашему формату сообщения фиксации ?
- Вы автор патча и новый участник? Добавьте себя в
AUTHORS
файл и отправьте лицензионное соглашение с участником .