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

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

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

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

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

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

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

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

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

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

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

• Код, необходимый для устранения проблемы или добавления функции, является важной частью патча, но не единственной. Хороший патч должен также включать 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 на билете установлены так, чтобы билет появился в этой очереди.