Представление материалов¶

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

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

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

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

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

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

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

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

Стиль вклада¶

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

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

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

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

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

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

Материалы, требующие обратной связи с сообществом¶

:ref:`deprecation <deprecating-a-feature>`Материалы, требующие обратной связи с сообществом

Материалы, требующие обратной связи с сообществом

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

Есть несколько причин, по которым код в 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) as ctx:
        # invoke deprecated behavior
        ...
    self.assertEqual(ctx.filename, __file__)

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

import warnings
from django.utils.deprecation import RemovedInDjangoXXWarning


# RemovedInDjangoXXWarning.
def old_private_helper():
    # Helper function that is only used in foo().
    pass


def foo():
    warnings.warn(
        "foo() is deprecated.",
        category=RemovedInDjangoXXWarning,
        stacklevel=2,
    )
    old_private_helper()
    ...

Наконец, необходимо сделать пару обновлений в документации Django:

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

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

Вклады в JavaScript¶

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

Оптимизационные патчи¶

Исправления, направленные на повышение производительности, должны содержать контрольные показатели, показывающие влияние исправления до и после, а также общие команды для воспроизведения рецензентами.

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

Используйте этот контрольный список для проверки запроса на повторное использование. Если этот вклад не будет considered trivial, сначала убедитесь, что он имеет статус принятого, прежде чем продолжить проверку.

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

Если вы хотите стать участником triage & review team, проведение тщательной проверки вкладов - отличный способ завоевать доверие.

Ищете патч для проверки? Ознакомьтесь с разделом «Исправления, требующие проверки» в Django Development Dashboard.

Хотите, чтобы ваш запрос на извлечение был рассмотрен? Убедитесь, что в заявке установлены флажки отслеживания, чтобы заявка появилась в этой очереди.