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

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

Более подробную информацию о пул-реквестах см. в Работа с Git и GitHub.

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

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

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

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

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

• Если тикета по этой проблеме еще нет, создайте его в нашем тикет трекере.

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

• Log into your account, if you haven’t already, by clicking «GitHub Login» or «DjangoProject Login» in the upper left of the ticket page.

• Claim the ticket by clicking the «assign to myself» radio button under «Action» near the bottom of the page, then click «Submit changes.»

Patch style¶

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

• The code required to fix a problem or add a feature is an essential part of a patch, but it is not the only part. A good patch should also include a regression test to validate the behavior that has been fixed and to prevent the problem from arising again. Also, if some tickets are relevant to the code that you’ve written, mention the ticket numbers in some comments in the test so that one can easily trace back the relevant discussions after your patch gets committed, and the tickets get closed.

• If the code associated with a patch adds a new feature, or modifies behavior of an existing feature, the patch should also contain documentation.

When you think your work is ready to be reviewed, send a GitHub pull request. Please review the patch yourself using our patch review checklist first.

If you can’t send a pull request for some reason, you can also use patches in Trac. When using this style, follow these guidelines.

• Отправляйте патчи в формате, возвращаемом командой git diff.

• Прикрепите исправления к тикету в трекере тикетов, используя кнопку «attach file». Пожалуйста, не помещайте исправление в описание тикета или комментарий, если это не исправление в одну строку.

• Назовите файл исправления расширением .diff; это позволит системе отслеживания тикетов применить правильную подсветку синтаксиса, что весьма полезно.

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

• Make sure your code fulfills the requirements in our patch review checklist.

• Установите флажок «Has patch» в тикете и убедитесь, что флажки «Needs documentation», «Needs tests» и «Patch needs improvement» не отмечены. Это приведет к тому, что тикет появится в очереди «Patches needing review» на Панели управления разработкой.

Non-trivial patches¶

A «non-trivial» patch is one that is more than a small bug fix. It’s a patch that introduces Django functionality and makes some sort of design decision.

If you provide a non-trivial patch, include evidence that alternatives have been discussed on django-developers.

If you’re not sure whether your patch should be considered non-trivial, ask on the ticket for opinions.

Депрекация функции¶

Есть несколько причин, по которым код в 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):
       ...
   

You can also add a test for the deprecation warning:

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) под соответствующей версией, описывающую, какой код будет удален.

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

Патчи JavaScript¶

For information on JavaScript patches, see the Патчи JavaScript documentation.

Patch review checklist¶

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, committers 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 committer, doing thorough reviews of patches is a great way to earn trust.

Looking for a patch to review? Check out the «Patches needing review» section of the Django Development Dashboard. Looking to get your patch reviewed? Ensure the Trac flags on the ticket are set so that the ticket appears in that queue.