KIKIMR-22202 Changes in PR template and docs for contributors with requirements to PR description (#14031)

Co-authored-by: Ivan Blinkov <[email protected]>

Author: galnat

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
-### Changelog entry <!-- a user-readable short description of changes introduced in this PR -->
+### Changelog entry <!-- a user-readable short description of the changes that goes to CHANGELOG.md and Release Notes -->
 
 ...
 
@@ -8,11 +8,12 @@
 * Experimental feature
 * Improvement
 * Performance improvement
+* User Interface
 * Bugfix 
 * Backward incompatible change
 * Documentation (changelog entry is not required)
 * Not for changelog (changelog entry is not required)
 
-### Additional information
+### Description for reviewers <!-- (optional) description for those who read this PR -->
 
 ...

.github/workflows/pr_labels.yaml

@@ -27,6 +27,7 @@ jobs:
               ['* Experimental feature', 'experimental-feature'],
               ['* Improvement', 'improvement'],
               ['* Performance improvement', 'performance'],
+              ['* User Interface', 'ui'],
               ['* Bugfix', 'bugfix'],
               ['* Backward incompatible change', 'backward-incompatible'],
               ['* Documentation', 'documentation'],

ydb/docs/ru/core/contributor/suggest-change.md

@@ -239,6 +239,101 @@ git push
 
 {% endlist %}
 
+### Заполните описание к Pull Request'у {#create_pr_desc}
+
+При создании Pull Request'а описание будет заполнено текстом из шаблона, который нужно отредактировать:
+
+1. **Changelog Category.** В этом блоке нужно оставить одну категорию из списка, которой соответствует изменение (см. [как выбрать категорию](#choose_category)). Есть категории, для которых сообщения из Changelog Entry можно не заполнять, они не будут опубликованы в списке изменений. Остальные категории определяют раздел списка изменений, в который попадёт сообщение.
+2. **Changelog Entry.** В этот блок следует добавить описание изменения для конечных пользователей системы (см. [требования](#changelog_entry_req)). Содержимое этого блока будет опубликовано в [списке изменений](../changelog-server.md), если PR будет замержен.
+3. **Description for reviewers.** В этот блок можно добавить ссылку на задачу и любую дополнительную информацию, которая будет полезна для ревью вашего изменения. Содержимое этого блока не попадёт в список изменений.
+
+
+#### Требования к Changelog Entry {#changelog_entry_req}
+
+Сообщение в Changelog Entry должно отвечать следующим требованиям:
+
+- должно быть написано на английском языке;
+- содержать не менее 20 символов, если [выбранная категория](#choose_category) имеет раздел в списке изменений;
+- опираться на термины, которые используются в [глоссарии](../concepts/glossary.md);
+- описывать, что в работе системы изменилось для конечного пользователя;
+- соответствовать дополнительным требованиям, определяемым выбранной категорией.
+
+
+#### Как выбрать Changelog Category {#choose_category}
+
+#|
+|| Категория | Раздел в списке изменений | Описание | Требования к сообщению ||
+|| Feature
+| Функциональность
+| Новая функциональность. Иногда выпускается под флагом для сохранения совместимости.
+
+Если вы делаете более одного PR'а в рамках задачи, эту категорию нужно выбрать только для финального коммита, а для промежуточных коммитов — Not for changelog.
+| Должно включать:
+
+  * ссылку на документацию (если описание превышает два предложения);
+  * описание того, как включить функциональность, если она выпускается под флагом (если описание превышает одно предложение, его также стоит вынести в документацию).
+||
+|| Experimental feature
+| Функциональность с пометкой «экспериментально»
+| Новая функциональность. Всегда выпускается под флагом для сохранения совместимости.
+
+Отличие от предыдущей категории в том, что даже после тестирования мы не можем гарантировать конечному пользователю корректную работу системы с этим изменением.
+| Должно включать:
+
+  * ссылку на документацию (если описание превышает два предложения);
+  * описание того, как включить функциональность (если описание превышает одно предложение, его также стоит вынести в документацию).
+||
+|| Improvement
+| Функциональность
+| Изменения существующей функциональности.
+| Должно включать ссылку на документацию (если описание превышает два предложения).
+||
+|| Performance improvement
+| Производительность
+| Изменения в производительности системы — ускорения, оптимизации, улучшения, которые привели к измеряемым изменениям в производительности.
+|
+||
+|| Bugfix
+| Исправления ошибок
+| Исправления ошибок, с которыми пользователь сталкивался или мог столкнуться в предыдущих релизных версиях.
+| Должно содержать:
+
+  * ссылку на задачу в GitHub;
+  * описание условий, при которых пользователь мог столкнуться с проблемой;
+  * описание проявления проблемы;
+  * описание способа исправления (необязательно, если логика работы системы принципиально не изменилась).
+||
+|| User Interface
+| {{ ydb-short-name }} UI
+| Любые изменения в {{ ydb-short-name }} UI
+|
+||
+|| Backward incompatible changes
+| Изменения с потерей обратной совместимости
+| Изменения с потерей обратной совместимости с предыдущими релизными версиями.
+| Должно содержать:
+
+  * инструкцию по обновлению кластера без downtime приложений, которые используют изменяемую функциональность;
+  * инструкцию по откату обновлений с кластера без downtime приложений.
+||
+|| Documentation
+| -
+| Изменения в документации.
+| Не будет опубликовано в истории изменений. Сообщение заполнять не нужно.
+||
+|| Not for Changelog
+| -
+| Изменения, которые не видны конечному пользователю — рефакторинг кода, тесты, CI/CD, изменения CHANGELOG.md, исправления ошибок в коде новой функциональности (которая не попала в предыдущие релизные версии).
+| Не будет опубликовано в истории изменений. Сообщение заполнять не нужно.
+||
+|#
+
+{% note info %}
+
+Важно выбрать только одну категорию, поэтому не рекомендуется включать в один PR изменения из разных категорий, например, новую функциональность и исправление ошибки. Однако если так случилось, следует выбрать категорию более важного для пользователя изменения, а в блок Changelog Entry добавить описание всех изменений.
+
+{% endnote %}
+
 ### Предварительные проверки {#precommit_checks}
 
 Перед мержем изменений выполняются прекоммитные проверки Pull Request'а.