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

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


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

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

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

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

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

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

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

Используйте этот контрольный список для проверки пул реквеста. Если вы проверяете пул реквест, который не принадлежит вам и соответствует всем критериям ниже, пожалуйста, установите «Triage Stage» в соответствующем тикете Trac на «Ready for checkin». Если вы оставили комментарии для улучшения запроса на включение, пожалуйста, отметьте соответствующие флажки в тикете Trac на основе результатов вашего обзора: «Patch needs improvement», «Needs documentation» и/или «Needs tests». По мере того, как позволяет время и интерес, мерджеры проводят окончательные проверки тикетов «Ready for checkin» и либо фиксируют изменения, либо возвращают их на уровень «Accepted», если требуется дополнительная работа. Если вы хотите стать мерджером, проведение тщательных проверок вкладов — отличный способ заслужить доверие.

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

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