From 2272d756ab49e38447ad7c2f4a04cad2321b31eb Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Sun, 5 Apr 2020 16:16:35 +1000
Subject: [PATCH] Add specific notes about what is not API

By: md_5 <git@md-5.net>
---
 .../main/java/org/bukkit/package-info.java    | 22 +++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/paper-api/src/main/java/org/bukkit/package-info.java b/paper-api/src/main/java/org/bukkit/package-info.java
index da7d9f12c5..f4f8efcd03 100644
--- a/paper-api/src/main/java/org/bukkit/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/package-info.java
@@ -1,5 +1,23 @@
 /**
- * More generalized classes in the API.
+ * The root package of the Bukkit API, contains generalized API classes.
+ *
+ * Note: While the Bukkit API makes every effort to ensure stability, this is
+ * not guaranteed, especially across major versions. In particular the following
+ * is a (incomplete) list of things that are <b>not</b> API.
+ * <ul>
+ * <li>Implementing interfaces. The Bukkit API is designed to only be
+ * implemented by server software. Unless a class/interface is obviously
+ * designed for extension (eg {@link org.bukkit.scheduler.BukkitRunnable}), or
+ * explicitly marked as such, it should not be implemented by plugins. Although
+ * this can sometimes work, it is not guaranteed to do so and resulting bugs
+ * will be disregarded.</li>
+ * <li>Constructing inbuilt events. Although backwards compatibility is
+ * attempted where possible, it is sometimes not possible to add new fields to
+ * events without breaking existing constructors. To ensure that the API
+ * continues to evolve, event constructors are therefore not plugin API.</li>
+ * <li>Implementation classes. Concrete implementation classes packaged with
+ * Bukkit (eg those beginning with Simple) are not API. You should access them
+ * via their interfaces instead.</li>
+ * </ul>
  */
 package org.bukkit;
-