From cf25990719d8f1424d001f65d362bd8e984cf4a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yann=20C=C3=A9bron?= <yann.cebron@jetbrains.com>
Date: Wed, 13 Mar 2024 10:47:02 +0100
Subject: [PATCH] api changes: clarify instructions

---
 reference_guide/api_changes_list_2019.md | 17 ++++++++++-------
 reference_guide/api_changes_list_2020.md | 16 +++++++++-------
 reference_guide/api_changes_list_2021.md | 14 ++++++++------
 reference_guide/api_changes_list_2022.md | 10 ++++++----
 reference_guide/api_changes_list_2023.md |  4 +++-
 reference_guide/api_changes_list_2024.md |  6 ++++--
 6 files changed, 40 insertions(+), 27 deletions(-)

diff --git a/reference_guide/api_changes_list_2019.md b/reference_guide/api_changes_list_2019.md
index 26eba1f18..874978a3d 100644
--- a/reference_guide/api_changes_list_2019.md
+++ b/reference_guide/api_changes_list_2019.md
@@ -1,15 +1,17 @@
-# Incompatible Changes in IntelliJ Platform and Plugins API 2019.*
-
 <!-- Copyright 2000-2023 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 
+# Incompatible Changes in IntelliJ Platform and Plugins API 2019.*
+
 <!--
-Before documenting a breaking API change, please, make sure that the change cannot be avoided in an alternative way.
+Before documenting a breaking API change, please make sure that the change cannot be avoided in an alternative way.
 
-APIs marked with @ApiStatus.Experimental, @ApiStatus.Internal, or @ApiStatus.ScheduledForRemoval don't need to be documented.
+APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal/IntellijInternalApi, or @ApiStatus.ScheduledForRemoval don't need to be documented.
 
-To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description and recommended fix/action.
+To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description
+and recommended fix/action (please write full sentence ending with '.', see existing entries as reference).
+Non-platform changes must be grouped under relevant section for plugin.
 
-The following problem patterns are supported:
+The following problem patterns are supported and must be followed EXACTLY:
 
 <package name> package removed
 
@@ -29,6 +31,7 @@ The following problem patterns are supported:
 <class name>.<method name> method <parameter name> parameter marked @<class name>
 <class name> (class|interface) now (extends|implements) <class name> and inherits its final method <method name>(<human-readable parameters>)?
 <class name> (class|interface) now (extends|implements) <class name> and inherits its abstract method <method name>(<human-readable parameters>)?
+<class name> class now interface
 
 <class name>(<human-readable parameters>) constructor removed
 <class name>(<human-readable parameters>) constructor parameter <type> removed
@@ -56,7 +59,7 @@ An example of a ticket is https://youtrack.jetbrains.com/issue/MP-1218. Until su
 
 NOTE: You are allowed to prettify the pattern using links: [`org.example.Foo`](https://github.com/JetBrains/intellij-community/tree/master/)
 
-NOTE: Entries not starting with code quotes (`name`) can be added to document non-code changes  and will be skipped in API verification.
+NOTE: Entries not starting with code quotes (`name`) can be added to document non-code changes and will be skipped in API verification.
 -->
 
 <link-summary>List of known Breaking API Changes in 2019.*</link-summary>
diff --git a/reference_guide/api_changes_list_2020.md b/reference_guide/api_changes_list_2020.md
index cc700741a..de874a828 100644
--- a/reference_guide/api_changes_list_2020.md
+++ b/reference_guide/api_changes_list_2020.md
@@ -1,15 +1,17 @@
+<!-- Copyright 2000-2024 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
 # Incompatible Changes in IntelliJ Platform and Plugins API 2020.*
 
-<!-- Copyright 2000-2023 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
 <!--
-Before documenting a breaking API change, please, make sure that the change cannot be avoided in an alternative way.
+Before documenting a breaking API change, please make sure that the change cannot be avoided in an alternative way.
 
-APIs marked with @ApiStatus.Experimental, @ApiStatus.Internal, or @ApiStatus.ScheduledForRemoval don't need to be documented.
+APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal/IntellijInternalApi, or @ApiStatus.ScheduledForRemoval don't need to be documented.
 
-To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description and recommended fix/action.
+To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description
+and recommended fix/action (please write full sentence ending with '.', see existing entries as reference).
+Non-platform changes must be grouped under relevant section for plugin.
 
-The following problem patterns are supported:
+The following problem patterns are supported and must be followed EXACTLY:
 
 <package name> package removed
 
@@ -57,7 +59,7 @@ An example of a ticket is https://youtrack.jetbrains.com/issue/MP-1218. Until su
 
 NOTE: You are allowed to prettify the pattern using links: [`org.example.Foo`](https://github.com/JetBrains/intellij-community/tree/master/)
 
-NOTE: Entries not starting with code quotes (`name`) can be added to document non-code changes  and will be skipped in API verification.
+NOTE: Entries not starting with code quotes (`name`) can be added to document non-code changes and will be skipped in API verification.
 -->
 
 <link-summary>List of known Breaking API Changes in 2020.*</link-summary>
diff --git a/reference_guide/api_changes_list_2021.md b/reference_guide/api_changes_list_2021.md
index dfa97f2db..459c7a6b2 100644
--- a/reference_guide/api_changes_list_2021.md
+++ b/reference_guide/api_changes_list_2021.md
@@ -1,15 +1,17 @@
-# Incompatible Changes in IntelliJ Platform and Plugins API 2021.*
+<!-- Copyright 2000-2024 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 
-<!-- Copyright 2000-2023 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+# Incompatible Changes in IntelliJ Platform and Plugins API 2021.*
 
 <!--
 Before documenting a breaking API change, please make sure that the change cannot be avoided in an alternative way.
 
-APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal, or @ApiStatus.ScheduledForRemoval don't need to be documented.
+APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal/IntellijInternalApi, or @ApiStatus.ScheduledForRemoval don't need to be documented.
 
-To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description and recommended fix/action.
+To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description
+and recommended fix/action (please write full sentence ending with '.', see existing entries as reference).
+Non-platform changes must be grouped under relevant section for plugin.
 
-The following problem patterns are supported:
+The following problem patterns are supported and must be followed EXACTLY:
 
 <package name> package removed
 
@@ -57,7 +59,7 @@ An example of a ticket is https://youtrack.jetbrains.com/issue/MP-1218. Until su
 
 NOTE: You are allowed to prettify the pattern using links: [`org.example.Foo`](https://github.com/JetBrains/intellij-community/tree/master/)
 
-NOTE: Entries not starting with code quotes (`name`) can be added to document non-code changes  and will be skipped in API verification.
+NOTE: Entries not starting with code quotes (`name`) can be added to document non-code changes and will be skipped in API verification.
 -->
 
 <link-summary>List of known Breaking API Changes in 2021.*</link-summary>
diff --git a/reference_guide/api_changes_list_2022.md b/reference_guide/api_changes_list_2022.md
index 794b12f2f..c5b94b6be 100644
--- a/reference_guide/api_changes_list_2022.md
+++ b/reference_guide/api_changes_list_2022.md
@@ -1,15 +1,17 @@
-# Incompatible Changes in IntelliJ Platform and Plugins API 2022.*
+<!-- Copyright 2000-2024 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 
-<!-- Copyright 2000-2023 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+# Incompatible Changes in IntelliJ Platform and Plugins API 2022.*
 
 <!--
 Before documenting a breaking API change, please make sure that the change cannot be avoided in an alternative way.
 
 APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal/IntellijInternalApi, or @ApiStatus.ScheduledForRemoval don't need to be documented.
 
-To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description and recommended fix/action.
+To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description
+and recommended fix/action (please write full sentence ending with '.', see existing entries as reference).
+Non-platform changes must be grouped under relevant section for plugin.
 
-The following problem patterns are supported:
+The following problem patterns are supported and must be followed EXACTLY:
 
 <package name> package removed
 
diff --git a/reference_guide/api_changes_list_2023.md b/reference_guide/api_changes_list_2023.md
index 52ee567e4..e36d37868 100644
--- a/reference_guide/api_changes_list_2023.md
+++ b/reference_guide/api_changes_list_2023.md
@@ -7,7 +7,9 @@ Before documenting a breaking API change, please make sure that the change canno
 
 APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal/IntellijInternalApi, or @ApiStatus.ScheduledForRemoval don't need to be documented.
 
-To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description and recommended fix/action.
+To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description
+and recommended fix/action (please write full sentence ending with '.', see existing entries as reference).
+Non-platform changes must be grouped under relevant section for plugin.
 
 The following problem patterns are supported and must be followed EXACTLY:
 
diff --git a/reference_guide/api_changes_list_2024.md b/reference_guide/api_changes_list_2024.md
index 630c94ac5..975ac88ad 100644
--- a/reference_guide/api_changes_list_2024.md
+++ b/reference_guide/api_changes_list_2024.md
@@ -7,7 +7,9 @@ Before documenting a breaking API change, please make sure that the change canno
 
 APIs marked with @Deprecated(forRemoval=true), @ApiStatus.Experimental, @ApiStatus.Internal/IntellijInternalApi, or @ApiStatus.ScheduledForRemoval don't need to be documented.
 
-To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description and recommended fix/action.
+To document a new incompatible change, add a new line with the problem pattern followed by a 2nd line with ": "-prefixed human-readable description
+and recommended fix/action (please write full sentence ending with '.', see existing entries as reference).
+Non-platform changes must be grouped under relevant section for plugin.
 
 The following problem patterns are supported and must be followed EXACTLY:
 
@@ -73,7 +75,7 @@ NOTE: Entries not starting with code quotes (`name`) can be added to document no
 ### IntelliJ Platform 2024.2
 
 `org.apache.sanselan.util` package removed
-: `org.apache.sanselan.util.IOUtils` compatibility shim is obsolete; instead, please use JRE methods or `org.apache.commons.io.IOUtils`
+: `org.apache.sanselan.util.IOUtils` compatibility shim is obsolete; instead, please use JRE methods or `org.apache.commons.io.IOUtils`.
 
 ## 2024.1