From 0c78faf3aae86b395aea7ff11a57248c510426ee Mon Sep 17 00:00:00 2001
From: Igor Demin <igordmn@users.noreply.github.com>
Date: Thu, 20 Feb 2025 17:02:41 +0100
Subject: [PATCH] Update Release Notes categories (#5240)

- Rename `Breaking Changes` to `Migration Notes`
- Add Lifecycle/Navigation. We used them in
[CHANGELOG.md](https://github.com/JetBrains/compose-multiplatform/blob/release/1.8.0-alpha03/CHANGELOG.md),
and have it in the script, but didn't have in the template
- Describe each category
- Use platform categories as general ones. It contradicts with my
comments
[here](https://github.com/JetBrains/compose-multiplatform/pull/5231#discussion_r1953385844)
and
[here](https://github.com/JetBrains/compose-multiplatform-core/pull/1844#discussion_r1958445125),
that it was only Compose related. But after thinking, we need some
category for changes that don't fall under Compose or any other existing
one. We can use platform categories (probably only Compose and some
Compose components fall into this category right now)

## Release Notes
N/A
---
 .github/PULL_REQUEST_TEMPLATE.md | 29 ++++++++++++++++-------------
 tools/changelog.main.kts         |  1 +
 2 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 13a5c22c76..c8a727a830 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -20,24 +20,27 @@ If we definitely shouldn't add Release Notes, add only N/A.
 Or enumerate sections, subsections and all changes.
 
 Possible sections:
-- Highlights
-- Known Issues
-- Breaking Changes
-- Features
-- Fixes
+- Highlights             // major features
+- Known Issues           // issues planned to be fixed, with possible workarounds
+- Breaking Changes       // incompatible changes without deprecation cycle
+- Migration Notes        // deprecations, removals, minimal version increases, defined behavior changes
+- Features               // minor features
+- Fixes                  // bug fixes, undefined behavior changes
 
 Possible subsections:
-- Multiple Platforms
-- iOS
-- Desktop
-- Web
-- Android
-- Resources
-- Gradle Plugin
+- Multiple Platforms     // any module, 2 or more platform changes
+- iOS                    // any module, iOS-only changes
+- Desktop                // any module, Desktop-only changes
+- Web                    // any module, Web-only changes
+- Android                // any module, Android-only changes
+- Resources              // specific module, prefer it over the platform ones
+- Gradle Plugin          // specific module, prefer it over the platform ones
+- Lifecycle              // specific module, prefer it over the platform ones
+- Navigation             // specific module, prefer it over the platform ones
 -->
 ### Section - Subsection
 - Describe a change for adding it to https://github.com/JetBrains/compose-multiplatform/blob/master/CHANGELOG.md
-- _(prerelease fix)_ Fix some bug that introduced in a prerelease version (dev/beta). It will be included in a dev/beta changelog, but excluded from a stable changelog
+- _(prerelease fix)_ Fix some bug that introduced in a prerelease version (alpha/beta/rc). It will be included in a alpha/beta/rc changelog, but excluded from a stable changelog
 
 ### Section - Subsection
 - Describe another change if needed
diff --git a/tools/changelog.main.kts b/tools/changelog.main.kts
index 002942779e..b781a75313 100644
--- a/tools/changelog.main.kts
+++ b/tools/changelog.main.kts
@@ -60,6 +60,7 @@ val standardSections = listOf(
     "Highlights",
     "Known Issues",
     "Breaking Changes",
+    "Migration Notes",
     "Features",
     "Fixes",
 )