Добавление информации об изменениях в примечаниях к выпуску

Многие инструменты BeeWare используют towncrier для помощи в создании примечаний к каждому выпуску. Когда вы отправляете запрос на извлечение в один из соответствующих инструментов, он должен включать примечание об изменении — это примечание станет записью в примечаниях к выпуску, описывающей внесенное изменение.

Каждый пул-реквест должен содержать как минимум один файл в каталоге changes/, в котором дается краткое описание изменений, внесенных пул-реквестом. Заметка об изменениях должна быть в формате Markdown, в файле с именем формата <id>.<fragment type>.md. Если предлагаемое вами изменение исправляет ошибку или реализует функцию, для которой уже существует номер проблемы, то идентификатором будет номер этого тикета. Если изменение не имеет соответствующей проблемы, в качестве идентификатора можно использовать номер PR. Вы не узнаете этот номер PR, пока не отправите запрос на извлечение, поэтому первая проверка CI не пройдет проверку towncrier; добавьте примечание об изменении и отправьте обновление PR, после чего CI должна пройти.

Существует пять типов фрагментов:

• feature: PR добавляет новое поведение или возможность, которые ранее были недоступны (например, добавление поддержки нового формата упаковки или новой функции в существующем формате упаковки);
• bugfix: PR исправляет ошибку в существующей реализации;
• doc: PR значительно улучшает документацию;
• removal; The PR represents a backwards incompatible change in the BeeWare API; or
• misc; Незначительное или административное изменение (например, исправление опечатки, незначительное уточнение формулировки или обновление версии зависимости), которое не требует объявления в примечаниях к выпуску.

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

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

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

Соответствующее примечание об изменении будет выглядеть примерно так:

Названия проектов больше не могут начинаться с цифры.

Некоторые PR могут вводить несколько функций и исправлять несколько ошибок, либо вводить несколько изменений, несовместимых с предыдущими версиями. В этом случае PR может иметь несколько файлов с примечаниями об изменениях. Если вам нужно связать два типа фрагментов с одним и тем же ID, вы можете добавить числовой суффикс. Например, если PR 789 добавил функцию, описанную в тикете 123, закрыл ошибку, описанную в тикете 234, а также внес два изменения, несовместимых с предыдущими версиями, у вас может быть 4 файла с примечаниями об изменениях:

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

Для получения дополнительной информации о towncrier и типах фрагментов см. Фрагменты новостей. Вы также можете посмотреть существующие примеры фрагментов новостей в каталоге changes репозитория BeeWare. Если эта папка пуста, вероятно, BeeWare недавно опубликовал новую версию; файлы с изменениями удаляются и объединяются для обновления примечаний к выпуску с каждым выпуском. Вы можете посмотреть этот файл, чтобы увидеть требуемый стиль комментариев; вы можете посмотреть недавно объединенные PR, чтобы увидеть, как форматировать свои заметки об изменениях.