Отправка патчей ¶

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

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

См. Раздел Работа с Git и GitHub для получения дополнительных сведений о том, как использовать запросы на вытягивание.

«Получение» билетов ¶

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

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

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

• Войдите в систему, используя свою учетную запись GitHub, или создайте учетную запись в нашей системе билетов. Если у вас есть учетная запись, но вы забыли пароль, вы можете сбросить ее на странице сброса пароля .
• Если билет для этой проблемы еще не существует, создайте его в нашем трекере билетов .
• Если билет по этой проблеме уже существует, убедитесь, что никто его не забрал. Для этого посмотрите в разделе заявки «Принадлежит». Если он назначен «никому», то он доступен для востребования. В противном случае над этой заявкой может работать кто-то другой. Либо найдите другую ошибку / функцию, над которой нужно поработать, либо обратитесь к разработчику, работающему над тикетом, чтобы предложить свою помощь. Если билет был назначен на недели или месяцы без каких-либо действий, вероятно, безопасно переназначить его самому себе.
• Войдите в свою учетную запись, если вы еще этого не сделали, нажав «Вход в GitHub» или «Вход в DjangoProject» в левом верхнем углу страницы заявки.
• Получите билет, щелкнув переключатель «назначить себе» в разделе «Действие» в нижней части страницы, а затем нажмите «Отправить изменения».

Стиль патча ¶

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

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

Когда вы считаете, что ваша работа готова к рассмотрению, отправьте запрос на перенос на 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.pyRemovedInDjangoXXWarning

Первый шаг - отменить любое использование устаревшего поведения самим 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) под заголовком «Функции, не рекомендуемые в AB».
3. Добавьте запись на временную шкалу устаревания ( docs/internals/deprecation.txt) под соответствующей версией, описывающую, какой код будет удален.

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

Патчи JavaScript ¶

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

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

Используйте этот контрольный список для просмотра запроса на вытягивание. Если вы просматриваете чужой запрос на перенос и он соответствует всем нижеприведенным критериям, установите для параметра «Этап сортировки» в соответствующем билете Trac значение «Готово к регистрации». Если вы оставили комментарии для улучшения запроса на вытягивание, отметьте соответствующие флажки в заявке Trac на основе результатов вашей проверки: «Исправление требует улучшения», «Требуется документация» и / или «Требуются тесты». Если позволяет время и интерес, коммиттеры проводят окончательную проверку билетов «Готовы к регистрации» и либо фиксируют исправление, либо возвращают его в состояние «Принято», если необходимо выполнить дальнейшие работы. Если вы хотите стать коммиттером, тщательная проверка исправлений - отличный способ заработать доверие.

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