Merge branch 'dev/feature' into feature/better-enchanted-condition

Author: sovdeeth

build.gradle

@@ -29,7 +29,7 @@ dependencies {
 	shadow group: 'org.bstats', name: 'bstats-bukkit', version: '3.1.0'
 	shadow group: 'net.kyori', name: 'adventure-text-serializer-bungeecord', version: '4.3.4'
 
-	implementation group: 'io.papermc.paper', name: 'paper-api', version: '1.21.4-R0.1-SNAPSHOT'
+	implementation group: 'io.papermc.paper', name: 'paper-api', version: '1.21.5-R0.1-SNAPSHOT'
 	implementation group: 'com.google.code.findbugs', name: 'findbugs', version: '3.0.1'
 
 	// bundled with Minecraft 1.19.4+ for display entity transforms
@@ -246,7 +246,7 @@ void createTestTask(String name, String desc, String environments, int javaVersi
 def java21 = 21
 def java17 = 17
 
-def latestEnv = 'java21/paper-1.21.4.json'
+def latestEnv = 'java21/paper-1.21.5.json'
 def latestJava = java21
 def oldestJava = java17
 

code-conventions.md

@@ -314,3 +314,14 @@ The exceptions are `Material.AIR`, which is a good way to represent "nothing"
 and `Material.STONE` which can be used to get a dummy `ItemMeta`.
 
 Prefer to avoid referencing the Biome enum directly, since it has changed between versons in the past.
+
+### Deprecating
+
+When deprecating a Java element (such as a class, method, or constructor):
+
+1. Replace all internal usages of the deprecated element within the Skript codebase.
+2. Add a Javadoc `@deprecated` tag that states the recommended alternative.
+3. Annotate the element with `@Deprecated(since = "INSERT VERSION", forRemoval = true)` to indicate it is scheduled for removal and what feature version it was deprecated.
+
+Deprecation PRs are typically merged for a feature release, so the PR should target `dev/feature` branch.
+Deprecated elements may be removed three feature releases after the version they were deprecated in.

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.parallel=true
 
 groupid=ch.njol
 name=skript
-version=2.11.0
+version=2.11.1
 jarName=Skript.jar
-testEnv=java21/paper-1.21.4
+testEnv=java21/paper-1.21.5
 testEnvJavaVersion=21

src/main/java/ch/njol/skript/Skript.java

@@ -210,7 +210,7 @@ public static void updateMinecraftVersion() {
 
 	@Nullable
 	private static Version version = null;
-	@Deprecated(forRemoval = true) // TODO this field will be replaced by a proper registry later
+	@Deprecated(since = "2.9.0", forRemoval = true) // TODO this field will be replaced by a proper registry later
 	private static @UnknownNullability ExperimentRegistry experimentRegistry;
 
 	public static Version getVersion() {
@@ -1077,18 +1077,6 @@ public static boolean isRunningMinecraft(final Version v) {
 		return minecraftVersion.compareTo(v) >= 0;
 	}
 
-	/**
-	 * Used to test whether certain Bukkit features are supported.
-	 *
-	 * @param className
-	 * @return Whether the given class exists.
-	 * @deprecated use {@link #classExists(String)}
-	 */
-	@Deprecated
-	public static boolean supports(final String className) {
-		return classExists(className);
-	}
-
 	/**
 	 * Tests whether a given class exists in the classpath.
 	 *
@@ -1379,7 +1367,7 @@ private static void stopAcceptingRegistrations() {
 
 	// ================ ADDONS ================
 
-	@Deprecated
+	@Deprecated(since = "2.10.0", forRemoval = true)
 	private static final Set<SkriptAddon> addons = new HashSet<>();
 
 	/**
@@ -1429,7 +1417,7 @@ public static SkriptAddon registerAddon(JavaPlugin plugin) {
 		return Collections.unmodifiableCollection(addons);
 	}
 
-	@Deprecated
+	@Deprecated(since = "2.10.0", forRemoval = true)
 	private static @Nullable SkriptAddon addon;
 
 	/**

src/main/java/ch/njol/skript/SkriptCommand.java

@@ -514,10 +514,10 @@ private static List<File> getSubFiles(File file) {
 	}
 
 	/**
-	 * Moved to {@link ScriptLoader#getScriptFromName(String)}
+	 * @deprecated Use {@link ScriptLoader#getScriptFromName(String)} instead.
 	 */
 	@Nullable
-	@Deprecated(forRemoval = true)
+	@Deprecated(since = "2.10.0", forRemoval = true)
 	public static File getScriptFromName(String script) {
 		return ScriptLoader.getScriptFromName(script);
 	}

src/main/java/ch/njol/skript/SkriptConfig.java

@@ -203,7 +203,7 @@ public static String formatDate(final long timestamp) {
 		new Option<>("disable starting a variable's name with an expression warnings", false);
 	public static final Option<Boolean> disableUnreachableCodeWarnings = new Option<>("disable unreachable code warnings", false);
 
-	@Deprecated
+	@Deprecated(since = "2.3.0", forRemoval = true)
 	public static final Option<Boolean> enableScriptCaching = new Option<>("enable script caching", false)
 			.optional(true);
 

src/main/java/ch/njol/skript/SkriptEventHandler.java

@@ -251,10 +251,10 @@ public static void logTriggerEnd(Trigger t) {
 	}
 
 	/**
-	 * @deprecated This method no longer does anything as self registered Triggers
+	 * @deprecated This method no longer does anything as self registered Triggers.
 	 * 	are unloaded when the {@link ch.njol.skript.lang.SkriptEvent} is unloaded (no need to keep tracking them here).
 	 */
-	@Deprecated
+	@Deprecated(since = "2.7.0", forRemoval = true)
 	public static void addSelfRegisteringTrigger(Trigger t) { }
 
 	/**
@@ -337,7 +337,7 @@ public static void unregisterBukkitEvents(Trigger trigger) {
 	 * Events which are listened even if they are cancelled. This should no longer be used.
 	 * @deprecated Users should specify the listening behavior in the event declaration. "on any %event%:", "on cancelled %event%:".
 	 */
-	@Deprecated
+	@Deprecated(since = "2.9.0", forRemoval = true)
 	public static final Set<Class<? extends Event>> listenCancelled = new HashSet<>();
 
 	/**

src/main/java/ch/njol/skript/aliases/Aliases.java

@@ -381,7 +381,7 @@ public static void clear() {
 	 *
 	 * @deprecated Freezes server on call. Use {@link #loadAsync()} instead.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.10.0", forRemoval = true)
 	public static void load() {
 		try {
 			long start = System.currentTimeMillis();
@@ -608,7 +608,7 @@ public static EntityData<?> getRelatedEntity(ItemData data) {
 	 * @return An item.
 	 * @throws IllegalArgumentException When item is not found.
 	 */
-	@Deprecated(forRemoval = true, since = "2.9.0")
+	@Deprecated(since = "2.9.0", forRemoval = true)
 	public static ItemType javaItemType(String name) {
 		ItemType type = parseItemType(name);
 		if (type == null) {

src/main/java/ch/njol/skript/aliases/ItemData.java

@@ -68,9 +68,9 @@ public static class OldItemData {
 	/**
 	 * Before 1.13, data values ("block states") are applicable to items.
 	 *
-	 * @deprecated before 1.13 is no longer supported
+	 * @deprecated before 1.13 is no longer supported.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.7.0", forRemoval = true)
 	public static final boolean itemDataValues = false;
 
 	/**
@@ -179,9 +179,9 @@ public ItemData(ItemStack stack) {
 	}
 
 	/**
-	 * @deprecated Use {@link ItemData#ItemData(BlockData)} instead
+	 * @deprecated Use {@link ItemData#ItemData(BlockData)} instead.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.8.4", forRemoval = true)
 	public ItemData(BlockState blockState) {
 		this(blockState.getBlockData());
 	}

src/main/java/ch/njol/skript/aliases/ItemType.java

@@ -174,9 +174,9 @@ public ItemType(ItemStack i) {
 	}
 
 	/**
-	 * @deprecated Use {@link #ItemType(BlockData)} instead
+	 * @deprecated Use {@link #ItemType(BlockData)} instead.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.8.4", forRemoval = true)
 	public ItemType(BlockState blockState) {
 		this(blockState.getBlockData());
 	}
@@ -268,9 +268,9 @@ public boolean isOfType(@Nullable ItemStack item) {
 	}
 
 	/**
-	 * @deprecated Use {@link #isOfType(BlockData)} instead
+	 * @deprecated Use {@link #isOfType(BlockData)} instead.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.8.4", forRemoval = true)
 	public boolean isOfType(@Nullable BlockState blockState) {
 		return blockState != null && isOfType(blockState.getBlockData());
 	}
@@ -1239,9 +1239,9 @@ public List<String> getRawNames() {
 	/**
 	 * Gets all enchantments of this item.
 	 * @return Enchantments.
-	 * @deprecated Use {@link ItemType#getEnchantmentTypes()}
+	 * @deprecated Use {@link ItemType#getEnchantmentTypes()} instead.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.3.0", forRemoval = true)
 	@Nullable
 	public Map<Enchantment,Integer> getEnchantments() {
 		if (globalMeta == null)
@@ -1256,9 +1256,9 @@ public Map<Enchantment,Integer> getEnchantments() {
 	/**
 	 * Adds enchantments to this item type.
 	 * @param enchantments Enchantments.
-	 * @deprecated Use {@link ItemType#addEnchantments(EnchantmentType...)}
+	 * @deprecated Use {@link ItemType#addEnchantments(EnchantmentType...)} instead.
 	 */
-	@Deprecated
+	@Deprecated(since = "2.3.0", forRemoval = true)
 	public void addEnchantments(Map<Enchantment,Integer> enchantments) {
 		if (globalMeta == null)
 			globalMeta = ItemData.itemFactory.getItemMeta(Material.STONE);