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

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

Если вы исправляете действительно тривиальную проблему, например, меняете слово в документации, предпочтительным способом предоставления исправления является использование 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.

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

Use this checklist to review a pull request. If you are reviewing a pull request that is not your own and it passes all the criteria below, please set the «Triage Stage» on the corresponding Trac ticket to «Ready for checkin». If you’ve left comments for improvement on the pull request, please tick the appropriate flags on the Trac ticket based on the results of your review: «Patch needs improvement», «Needs documentation», and/or «Needs tests». As time and interest permits, mergers do final reviews of «Ready for checkin» tickets and will either commit the patch or bump it back to «Accepted» if further works need to be done. If you’re looking to become a merger, doing thorough reviews of patches is a great way to earn trust.

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