Представление исправлений

Мы всегда благодарны за исправления к коду Django. Действительно, сообщения об ошибках с соответствующими исправлениями будут исправлены гораздо быстрее, чем сообщения без исправлений.

Исправления опечаток и тривиальные изменения в документации

Если вы исправляете действительно тривиальную проблему, например, меняете слово в документации, предпочтительным способом предоставления исправления является использование GitHub pull requests без тикета Trac.

Более подробную информацию о том, как использовать запросы на вытягивание, см. в Работа с Git и GitHub.

«Претендующие» билеты

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

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

Если вы определили вклад, который вы хотите внести, и вы способны его исправить (в соответствии с вашими способностями к кодированию, знанием внутренних компонентов Django и наличием времени), заявите о нем, выполнив следующие шаги:

  • Login using your GitHub account или create an account в нашей билетной системе. Если у вас есть учетная запись, но вы забыли пароль, вы можете восстановить его с помощью password reset page.
  • Если тикет по этому вопросу еще не существует, создайте его в нашем разделе ticket tracker.
  • Если билет по этой проблеме уже существует, убедитесь, что никто другой на него не претендовал. Для этого посмотрите на раздел «Принадлежит» в билете. Если он принадлежит «никому», значит, на него можно претендовать. В противном случае, возможно, над этим билетом работает кто-то другой. Либо найдите другую ошибку/функцию, над которой можно поработать, либо свяжитесь с разработчиком, работающим над этим билетом, и предложите свою помощь. Если билет был назначен на несколько недель или месяцев без какой-либо активности, вероятно, можно переназначить его на себя.
  • Войдите в свой аккаунт, если вы этого еще не сделали, нажав «GitHub Login» или «DjangoProject Login» в верхней левой части страницы тикета.
  • Утвердите билет, нажав радиокнопку «Назначить себе» в разделе «Действие» в нижней части страницы, затем нажмите «Отправить изменения».

Примечание

Программный фонд Django просит всех, кто вносит в Django более чем тривиальный патч, подписать и отправить Contributor License Agreement, это гарантирует, что программный фонд Django имеет четкую лицензию на все вклады, что позволяет иметь четкую лицензию для всех пользователей.

Ответственность предъявителей билетов

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

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

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

Как всегда, больше общения лучше, чем меньше!

Какие билеты должны быть востребованы?

В некоторых случаях прохождение этапов утверждения билетов является излишеством.

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

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

Накладной стиль

Убедитесь, что любой ваш вклад соответствует, по крайней мере, следующим требованиям:

  • Код, необходимый для устранения проблемы или добавления функции, является важной частью патча, но не единственной. Хороший патч должен также включать regression test, чтобы подтвердить поведение, которое было исправлено, и предотвратить повторное возникновение проблемы. Также, если некоторые тикеты имеют отношение к написанному вами коду, укажите номера тикетов в комментариях в тесте, чтобы можно было легко отследить соответствующие обсуждения после того, как ваш патч будет зафиксирован, а тикеты закрыты.
  • Если код, связанный с патчем, добавляет новую функцию или изменяет поведение существующей функции, патч также должен содержать документацию.

Когда вы считаете, что ваша работа готова к рецензированию, отправьте a GitHub pull request. Пожалуйста, сначала просмотрите патч самостоятельно, используя наш patch review checklist.

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

  • Отправьте патчи в формате, возвращаемом командой git diff.
  • Прикрепляйте патчи к тикету в ticket tracker, используя кнопку «прикрепить файл». Пожалуйста, не помещайте патч в описание или комментарий тикета, если только это не однострочный патч.
  • Назовите файл патча с расширением .diff; это позволит тикет-трекеру применить правильную подсветку синтаксиса, что весьма полезно.

Независимо от того, каким способом вы отправляете свою работу, выполните следующие шаги.

  • Убедитесь, что ваш код соответствует требованиям, приведенным в нашей статье patch review checklist.
  • Установите флажок «Имеет патч» в тикете и убедитесь, что флажки «Нужна документация», «Нужны тесты» и «Патч требует доработки» не установлены. Это заставит билет появиться в очереди «Патчи, требующие рассмотрения» на Development dashboard.

Нетривиальные заплаты

Нетривиальный» патч - это патч, который представляет собой нечто большее, чем небольшое исправление ошибки. Это патч, который вводит функциональность Django и принимает какое-то дизайнерское решение.

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

Если вы не уверены, следует ли считать ваш патч нетривиальным, спросите мнение в тикете.

Избавление от функции

Есть несколько причин, по которым код в Django может быть устаревшим:

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

Как описано в deprecation policy, первый выпуск Django, в котором функция устаревает (A.B), должен вызывать предупреждение RemovedInDjangoXXWarning (где XX - версия Django, в которой функция будет удалена) при вызове устаревшей функции. Предполагая, что у нас хорошее тестовое покрытие, эти предупреждения преобразуются в ошибки при running the test suite с включенными предупреждениями: python -Wa runtests.py. Таким образом, при добавлении RemovedInDjangoXXWarning необходимо устранить или заглушить любые предупреждения, генерируемые при выполнении тестов.

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

  1. В конкретном тесте:

    from django.test import ignore_warnings
    from django.utils.deprecation import RemovedInDjangoXXWarning
    
    @ignore_warnings(category=RemovedInDjangoXXWarning)
    def test_foo(self):
        ...
    
  2. Для всего тестового случая:

    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:

  1. Если существующая функция документирована, отметьте ее устаревшей в документации с помощью аннотации .. deprecated:: A.B. Включите краткое описание и примечание о пути обновления, если это применимо.
  2. Добавьте описание устаревшего поведения и путь обновления, если применимо, в примечания к текущему выпуску (docs/releases/A.B.txt) под заголовком «Функции, устаревшие в A.B».
  3. Добавьте запись во временной шкале износа (docs/internals/deprecation.txt) под соответствующей версией, описывающую, какой код будет удален.

Как только вы выполнили эти шаги, вы закончили амортизацию. В каждом feature release удаляются все RemovedInDjangoXXWarning, соответствующие новой версии.

Исправления JavaScript

Информацию об исправлениях JavaScript см. в документации Исправления JavaScript.

Контрольный список проверки исправлений

Используйте этот контрольный список для проверки запроса на исправление. Если вы рассматриваете не свой собственный запрос и он соответствует всем нижеприведенным критериям, установите «Triage Stage» в соответствующем Trac-билете на «Ready for checkin». Если вы оставили комментарии по улучшению заявки, пожалуйста, отметьте соответствующие флажки в билете Trac по результатам рассмотрения: «Патч нуждается в улучшении», «Нуждается в документации» и/или «Нуждается в тестах». Когда позволяет время и интерес, коммиттеры проводят окончательный анализ билетов «Ready for checkin» и либо фиксируют патч, либо возвращают его в статус «Accepted», если необходимо провести дополнительные работы. Если вы хотите стать коммиттером, проведение тщательной проверки патчей - отличный способ заслужить доверие.

Ищете патч для рецензирования? Загляните в раздел «Патчи, требующие рецензирования» в Django Development Dashboard. Хотите, чтобы ваш патч был рассмотрен? Убедитесь, что флаги Trac на билете установлены так, чтобы билет появился в этой очереди.

Документация

  • Собирается ли документация без ошибок (make html, или make.bat html в Windows, из каталога docs)?
  • Следует ли документация рекомендациям по стилю написания в Написание документации?
  • Есть ли такие spelling errors?

Жучки

  • Есть ли надлежащее регрессионное тестирование (тест должен быть неудачным до применения исправления)?
  • Если это ошибка, которая qualifies for a backport в стабильной версии Django, то есть ли примечание к релизу в docs/releases/A.B.C.txt? Исправления, которые будут применены только к основной ветке, не нуждаются в примечании к релизу.

Новые возможности

  • Существуют ли тесты для «тренировки» всего нового кода?
  • Есть ли примечание о выпуске в docs/releases/A.B.txt?
  • Есть ли документация для этой функции и является ли она annotated appropriately с .. versionadded:: A.B или .. versionchanged:: A.B?

Избавление от функции

См. руководство Избавление от функции.

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

  • Соответствует ли coding style нашим рекомендациям? Есть ли ошибки flake8? Вы можете установить крючки pre-commit, чтобы автоматически отлавливать эти ошибки.
  • Если изменение каким-либо образом обратно несовместимо, есть ли примечание в примечаниях к выпуску (docs/releases/A.B.txt)?
  • Проходит ли набор тестов Django?

Все билеты

  • Является ли pull request одним скомканным коммитом с сообщением, следующим за нашим commit message format?
  • Вы автор патча и новый вкладчик? Пожалуйста, добавьте себя в файл AUTHORS и отправьте Contributor License Agreement.
Вернуться на верх