Додавання інформації про зміни до приміток до випуску

Багато інструментів BeeWare використовують towncrier для полегшення створення приміток до кожного релізу. Коли ви надсилаєте запит на злиття (pull request) до одного з відповідних інструментів, він повинен містити примітку про зміну — ця примітка стане записом у примітках до релізу, що описує внесену зміну.

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

Існує п’ять типів фрагментів:

• feature: Цей PR додає нову функцію або можливість, яка раніше була недоступна (наприклад, додавання підтримки нового формату пакування або нової функції в існуючому форматі пакування);
• bugfix: Цей PR виправляє помилку в існуючій реалізації;
• doc: Цей прес-реліз є суттєвим вдосконаленням документації;
• removal; Цей PR передбачає зміну в API BeeWare, що несумісна з попередніми версіями; або
• misc; Незначна або адміністративна зміна (наприклад, виправлення друкарської помилки, незначне уточнення формулювання або оновлення версії залежності), про яку не потрібно повідомляти в примітках до випуску.

Цей опис у примітці до зміни має бути загальним «маркетинговим» резюме зміни з точки зору користувача, а не глибоким технічним описом чи деталями реалізації. Вона відрізняється від повідомлення про коміт — повідомлення про коміт описує, що було зроблено, щоб майбутні розробники могли зрозуміти логіку зміни; примітка про зміну — це опис, призначений для користувачів, які можуть не мати знань про внутрішні механізми роботи системи.

Наприклад, якщо ви виправили помилку, пов’язану з іменами проектів, повідомлення про коміт може виглядати так:

Застосувати більш суворі правила перевірки за допомогою регулярних виразів, щоб заборонити назви проектів, які починаються з цифр.

Відповідна записка про зміну могла б виглядати приблизно так:

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

Деякі PR можуть містити кілька нових функцій і виправлень помилок або кілька змін, несумісних із попередніми версіями. У такому випадку PR може мати кілька файлів з описом змін. Якщо вам потрібно пов’язати два типи фрагментів з одним і тим самим ідентифікатором, ви можете додати числовий суфікс. Наприклад, якщо PR 789 додав функцію, описану в квитку 123, виправив помилку, описану в квитку 234, а також вніс дві зміни, несумісні з попередніми версіями, у вас може бути 4 файли з примітками про зміни:

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

Більше інформації про towncrier та типи фрагментів див. у розділі Фрагменти новин. Ви також можете ознайомитися з існуючими прикладами фрагментів новин у каталозі changes репозиторію BeeWare. Якщо ця папка порожня, це, ймовірно, пов’язано з тим, що BeeWare нещодавно опублікував новий випуск; файли з примітками до змін видаляються та об’єднуються для оновлення приміток до випуску з кожним випуском. Ви можете переглянути цей файл, щоб ознайомитися з необхідним стилем коментарів; також можна переглянути нещодавно об’єднані PR, щоб дізнатися, як оформлювати свої нотатки про зміни.