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

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

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

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

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

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

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

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

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

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

• Войдите в свою учетную запись, если вы еще этого не сделали, нажав «GitHub Login» или «DjangoProject Login» в левом верхнем углу страницы тикета. После входа в систему вы можете нажать кнопку «Modify Ticket» в нижней части страницы.

• Примите тикет, нажав кнопку-переключатель «assign to» в разделе «Action». Ваше имя пользователя будет указано в текстовом поле по умолчанию.

• Наконец, нажмите кнопку «Submit changes» внизу, чтобы сохранить изменения.

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

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

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

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

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

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

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

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

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

• Убедитесь, что ваш код соответствует требованиям в нашем контрольном списке.

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

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

Требуется более широкое обсуждение в сообществе, когда патч вводит новую функциональность Django и принимает какое-либо решение по дизайну. Это особенно важно, если подход подразумевает депрекацию или вносит критические изменения.

Ниже приведены различные подходы к получению отзывов от сообщества.

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

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

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

import warnings
from django.utils.deprecation import RemovedInDjangoXXWarning, django_file_prefixes


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


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

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

1. Если существующая функция задокументирована, отметьте ее как устаревшую в документации, используя аннотацию .. deprecated:: A.B. Включите краткое описание и примечание о пути обновления, если применимо.

2. Добавьте описание устаревшего поведения и способ обновления, если он применимв текущие заметки о выпуске (docs/releases/A.B.txt) под заголовком «Функции, устаревшие в A.B».

3. Добавьте запись в шкалу времени депрекации (docs/internals/deprecation.txt) под соответствующей версией, описывающую, какой код будет удален.

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

Модуль django.utils.deprecation предоставляет некоторые полезные утилиты для устаревания, такие как декоратор @deprecate_posargs, который помогает преобразовать аргументы, содержащие позиционные или ключевые слова, в аргументы, содержащие только ключевые слова. См. встроенную документацию в исходном коде модуля.

Тестирование с помощью проекта Django¶

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

Для этого:

1. Создайте виртуальную среду и установите клонированную копию Django в редактируемом режиме.

2. Настройте проект Django вне дерева исходного кода (в качестве руководства вы можете использовать первую часть руководства).

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

Изменения в JavaScript¶

Информацию о написании JavaScript см. в документации Патчи JavaScript.

Патчи оптимизации¶

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

Чеклист внесения изменений¶

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

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

Если вы хотите стать членом команды сортировки и проверки, тщательная проверка вкладов — отличный способ завоевать доверие.

Ищете патч для обзора? Ознакомьтесь с разделом «Patches needing review» на Панели управления разработкой Django.

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