From 4890215965e53c51a09cf1f67b71675317e47dcf Mon Sep 17 00:00:00 2001
From: Sergey Patrikeev <sergey.patrikeev@jetbrains.com>
Date: Tue, 30 Jul 2019 13:32:26 +0300
Subject: [PATCH] api_changes_list_2019: insert tutorial at the top

---
 .../api_changes/api_changes_list_2019.md      | 46 +++++++++++++++++--
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/reference_guide/api_changes/api_changes_list_2019.md b/reference_guide/api_changes/api_changes_list_2019.md
index 8118a241d..1d7abb545 100644
--- a/reference_guide/api_changes/api_changes_list_2019.md
+++ b/reference_guide/api_changes/api_changes_list_2019.md
@@ -3,11 +3,51 @@ title: 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.
 
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 
-See the note on how to document new problems on the main page reference_guide/api_changes_list.md 
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 
+APIs marked with @ApiStatus.Experimental or @ApiStatus.Internal 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.
+
+The following problem patterns are supported:
+
+<package name> package removed
+<class name> class removed
+<class name> renamed to <new class name>
+
+<class name>.<method name>(<human-readable parameters>) method removed
+<class name>.<method name>(<human-readable parameters>) method return type changed from <before> to <after>
+<class name>.<method name>(<human-readable parameters>) method parameter <type> removed
+<class name>.<method name>(<human-readable parameters>) method parameter type changed from <before> to <after>
+<class name>.<method name>(<human-readable parameters>) method visibility changed from <before> to <after>
+<class name>.<method name>(<human-readable parameters>) method marked final
+<class name> (class|interface) now (extends|implements) <class name> and inherits its final method <method name>(<human-readable parameters>)?
+
+<class name>(<human-readable parameters>) constructor removed
+<class name>(<human-readable parameters>) constructor parameter <type> removed
+<class name>(<human-readable parameters>) constructor parameter type changed from <before> to <after>
+<class name>(<human-readable parameters>) constructor visibility changed from <before> to <after>
+
+<class name>.<field name> field removed
+<class name>.<field name> field type changed from <before> to <after>
+<class name>.<field name> field visibility changed from <before> to <after>
+
+<class name>.<method name>(<human-readable parameters>) abstract method added
+<class name> class moved to package <package name>
+
+where <class name> is a fully-qualified name of the class, e.g. com.intellij.openapi.actionSystem.AnAction$InnerClass.
+<method name> is the exact method's name. Note that constructors have dedicated patterns.
+<human-readable parameters> is a string representing parameters, which are not necessarily fully qualified. They do not affect the parser. For example, instead of (java.lang.Object, java.util.List, int) you are free to write (Object, List<String>, int).
+
+NOTE: If a change you're trying to document doesn't match any of the above patterns, fill in a ticket in the YouTrack. 
+An example of a ticket is https://youtrack.jetbrains.com/issue/PR-1218. Until supported, you may document the change as you prefer, and I will correct it later.
+
+NOTE: You are allowed to prettify the pattern using markdown-features:
+ 1) code quotes: `org.example.Foo.methodName`
+ 2) links [org.example.Foo](https://github.com/JetBrains/intellij-community/tree/master/)
+ 3) both code quotes and links: [`org.example.Foo`](https://github.com/JetBrains/intellij-community/tree/master/)
 -->
 
 # 2019.3