Отправка исправлений

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

Исправления орфографии и изменения документации

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

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

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

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

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

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

  • Войдите, используя свою учетную запись GitHub, или создайте учетную запись в нашей системе тикетов. Если у вас есть учетная запись, но вы забыли пароль, вы можете сбросить ее на странице сброса пароля .
  • Если заявки на эту проблему еще не существует, создайте ее в нашей системе отслеживания заявок .
  • Если билет для решения этой проблемы уже существует, убедитесь, что никто уже не занимается с ним. Для этого изучите раздел билетов. Если назначен , значит, доступен. Если нет, то, вероятно, над этой заявкой работает кто-то другой. Затем найдите другую ошибку или функцию или обратитесь к разработчику, работающему над заявкой, чтобы предложить помощь. Если билет был назначен кому-то в течение недель или месяцев без активности, его можно будет назначить вам без риска конфликта.Owned by nobody
  • Войдите в свою учетную запись, если вы еще этого не сделали, нажав «Вход в 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 декоратор, либо на уровне теста, либо на уровне класса:

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

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

Ошибки

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

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

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

Прекращение поддержки функции

См. Руководство по прекращению поддержки функций .

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

  • Соответствует ли стиль кода нашим рекомендациям? Код выдает ошибки flake8 ?
  • Если изменение каким-либо образом несовместимо с предыдущими версиями, есть ли соответствующее примечание к выпуску (в docs/releases/A.B.txt )?
  • Пройдет ли набор тестов Django?

Все билеты

Copyright ©2020 All rights reserved