Add 'AspectJ_JDK_Update' hint in various places

The hint is meant to help AspectJ developers identify the places where
there are to-dos for releases supporting new Java versions. This is work
in progress, new tags can be added wherever necessary in the future. But
for now, the most important places should be covered:

 - AJC version string
 - Test infrastructure (test suites, classes and XML files)
 - BCEL class file version MAJOR_*, MINOR_* constants
 - AjcTask constants for compiler source, target, release
 - LangUtil::is*VMOrGreater methods
 - ASM and JDT Core dependency versions
 - CI workflow file
 - Release notes

The to-do to check the tagged places is also mentioned in RELEASE.md.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

11 files changed, 33 insertions, 2 deletions

diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
index 159359d9e..4bc10c4a7 100644
--- a/.github/workflows/maven.yml
+++ b/.github/workflows/maven.yml
@@ -22,6 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # AspectJ_JDK_Update
         # Check for available Temurin releases on https://adoptium.net/releases.html
         java: [ 17, 21 ]
 
diff --git a/bcel-builder/src/main/java/org/aspectj/apache/bcel/Constants.java b/bcel-builder/src/main/java/org/aspectj/apache/bcel/Constants.java
index 14e6a7f29..5b96bb6d1 100644
--- a/bcel-builder/src/main/java/org/aspectj/apache/bcel/Constants.java
+++ b/bcel-builder/src/main/java/org/aspectj/apache/bcel/Constants.java
@@ -106,6 +106,7 @@ public interface Constants {
 	short MINOR_20 = 0;
 	short MAJOR_21 = 65;
 	short MINOR_21 = 0;
+	// AspectJ_JDK_Update
 //	short MAJOR_22 = 66;
 //	short MINOR_22 = 0;
 
diff --git a/docs/developer/RELEASE.md b/docs/developer/RELEASE.md
index 69db8a0f5..40e942233 100644
--- a/docs/developer/RELEASE.md
+++ b/docs/developer/RELEASE.md
@@ -73,6 +73,10 @@ manual versioning process without using Maven Release plugin. It might work usin
   - committing the snapshot POMs,
   - pushing the previous commits and the release tag to the upstream Git repository.
 
+If the AspectJ release also includes support for a new Java version, then before releasing AspectJ, search for the
+term `AspectJ_JDK_Update` across all files in the code base, also non-Java ones. Check, that you have not forgotten to
+add any necessary infrastructure or to increment version numbers as appropriate.  
+
 In order to show the details and give you more control over the process, you can do it step by step as follows:
 
 ```shell
diff --git a/docs/release/README-1.9.21.adoc b/docs/release/README-1.9.21.adoc
index 5179cb0da..de9447937 100644
--- a/docs/release/README-1.9.21.adoc
+++ b/docs/release/README-1.9.21.adoc
@@ -2,6 +2,9 @@
 :doctype: book
 :leveloffset: +1
 
+// AspectJ_JDK_Update: Each a.b.c release needs a new release notes document. For a.b.c.d minors, the existing a.b.c
+// document can be updated. After copying this document, remove the comment from the previous one.
+
 The releases 1.9.21 and 1.9.21.1 are described together in this document.
 
 = AspectJ 1.9.21.1
diff --git a/org.aspectj.ajdt.core/src/main/resources/org/aspectj/org/eclipse/jdt/internal/compiler/batch/messages_aspectj.properties b/org.aspectj.ajdt.core/src/main/resources/org/aspectj/org/eclipse/jdt/internal/compiler/batch/messages_aspectj.properties
index 0a4d93e62..be66883e8 100644
--- a/org.aspectj.ajdt.core/src/main/resources/org/aspectj/org/eclipse/jdt/internal/compiler/batch/messages_aspectj.properties
+++ b/org.aspectj.ajdt.core/src/main/resources/org/aspectj/org/eclipse/jdt/internal/compiler/batch/messages_aspectj.properties
@@ -1,4 +1,6 @@
 compiler.name = AspectJ Compiler
+# AspectJ_JDK_Update: Update not only for new Java versions, but each time JDT Core is updated with an upstream merge.
+# Always make sure to update to the latest merge commit ID and date of the latest upstream commit.
 compiler.version = Eclipse Compiler 8398f6c1210ec3 (13Feb2024) - Java21
 compiler.copyright =
 
diff --git a/pom.xml b/pom.xml
index e5fb0180c..cf84a47c9 100644
--- a/pom.xml
+++ b/pom.xml
@@ -27,8 +27,8 @@
 		<maven.javadoc.skip>true</maven.javadoc.skip>
 
 		<!-- Dependency versions -->
-		<jdt.core.version>1.9.21.1</jdt.core.version>
-		<asm.version>9.6</asm.version>
+		<jdt.core.version>1.9.21.1</jdt.core.version> <!-- AspectJ_JDK_Update -->
+		<asm.version>9.6</asm.version> <!-- AspectJ_JDK_Update -->
 		<lib.ant.version>1.6.3</lib.ant.version>
 		<lib.ant.xerces.version>2.6.2</lib.ant.xerces.version>
 		<lib.regexp.version>1.2</lib.regexp.version>
diff --git a/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java b/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java
index ab99fd670..0737127f9 100644
--- a/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java
+++ b/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java
@@ -250,14 +250,17 @@ public class AjcTask extends MatchingTask {
 
 	public static final String COMMAND_EDITOR_NAME = AjcTask.class.getName() + ".COMMAND_EDITOR";
 
+	// AspectJ_JDK_Update
 	static final String[] TARGET_INPUTS = new String[] {
 		"1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9", "9",
 		"10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21"
 	};
+	// AspectJ_JDK_Update
 	static final String[] SOURCE_INPUTS = new String[] {
 		"1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9", "9",
 		"10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21"
 	};
+	// AspectJ_JDK_Update
 	static final String[] COMPLIANCE_INPUTS = new String[] {
 		"-1.3", "-1.4", "-1.5", "-1.6", "-1.7", "-1.8", "-1.9", "-9",
 		"-10", "-11", "-12", "-13", "-14", "-15", "-16", "-17", "-18", "-19", "-20", "-21"
diff --git a/testing/src/test/java/org/aspectj/testing/XMLBasedAjcTestCaseForJava21Only.java b/testing/src/test/java/org/aspectj/testing/XMLBasedAjcTestCaseForJava21Only.java
index fb6795b3d..2c582c106 100644
--- a/testing/src/test/java/org/aspectj/testing/XMLBasedAjcTestCaseForJava21Only.java
+++ b/testing/src/test/java/org/aspectj/testing/XMLBasedAjcTestCaseForJava21Only.java
@@ -19,6 +19,7 @@ public abstract class XMLBasedAjcTestCaseForJava21Only extends XMLBasedAjcTestCa
 
 	@Override
 	public void setUp() throws Exception {
+		// AspectJ_JDK_Update
 		// Activate this block after upgrading to JDT Core Java 22
 		/*
 		throw new IllegalStateException(
@@ -27,6 +28,7 @@ public abstract class XMLBasedAjcTestCaseForJava21Only extends XMLBasedAjcTestCa
 				"This compiler does not support preview features of a previous version anymore."
 		);
 		*/
+		// AspectJ_JDK_Update
 		// Activate this block before upgrading to JDT Core Java 22
 		if (!LangUtil.is21VMOrGreater() || LangUtil.is22VMOrGreater()) {
 			throw new IllegalStateException(
diff --git a/tests/src/test/java/org/aspectj/systemtest/AllTests19.java b/tests/src/test/java/org/aspectj/systemtest/AllTests19.java
index dee55718c..665569ec7 100644
--- a/tests/src/test/java/org/aspectj/systemtest/AllTests19.java
+++ b/tests/src/test/java/org/aspectj/systemtest/AllTests19.java
@@ -43,6 +43,7 @@ public class AllTests19 {
 		suite.addTest(AllTestsAspectJ199.suite());
 		suite.addTest(AllTestsAspectJ1919.suite());
 		suite.addTest(AllTestsAspectJ1920.suite());
+		// AspectJ_JDK_Update
 		suite.addTest(AllTestsAspectJ1921.suite());
 		suite.addTest(AllTests18.suite());
 		// $JUnit-END$
diff --git a/tests/src/test/java/org/aspectj/systemtest/ajc1921/AllTestsAspectJ1921.java b/tests/src/test/java/org/aspectj/systemtest/ajc1921/AllTestsAspectJ1921.java
index 773ac9037..30b6728f1 100644
--- a/tests/src/test/java/org/aspectj/systemtest/ajc1921/AllTestsAspectJ1921.java
+++ b/tests/src/test/java/org/aspectj/systemtest/ajc1921/AllTestsAspectJ1921.java
@@ -11,6 +11,18 @@ import junit.framework.Test;
 import junit.framework.TestSuite;
 import org.aspectj.util.LangUtil;
 
+// AspectJ_JDK_Update
+//  - Copy 'ajc*' package with all classes to a new package, incrementing the version number in the package
+//  - Rename all classes, incrementing version numbers
+//  - Add this class to the suite in class AllTests19
+//  - Increment version numbers in strings, method calls and constants to the appropriate values, creating necessary
+//    methods and constants classes providing them, if they do not exist yet
+//  - Also increment references to 'ajc*.xml' and 'sanity-tests-*.xml' test definition, copying the previous
+//    tests/src/test/resources/org/aspectj/systemtest/ajc* directory, incrementing all names and adjusting the XML
+//    file contents appropriately
+//  - Search for other 'AspectJ_JDK_Update' hints in the repository, also performing the necessary to-dos there
+//  - Remove this comment from the previous class version after copying this one
+
 /**
  * @author Alexander Kriegisch
  */
@@ -23,6 +35,7 @@ public class AllTestsAspectJ1921 {
 			suite.addTest(SanityTestsJava21.suite());
 			suite.addTest(Ajc1921TestsJava.suite());
 		}
+		// AspectJ_JDK_Update
 		// Do not run tests using a previous compiler's preview features anymore. They would all fail.
 		// TODO: Comment out the following block when upgrading JDT Core to Java 22
 		if (LangUtil.is21VMOrGreater() && !LangUtil.is22VMOrGreater()) {
diff --git a/util/src/main/java/org/aspectj/util/LangUtil.java b/util/src/main/java/org/aspectj/util/LangUtil.java
index 2e7af3c39..9db8f629b 100644
--- a/util/src/main/java/org/aspectj/util/LangUtil.java
+++ b/util/src/main/java/org/aspectj/util/LangUtil.java
@@ -191,6 +191,7 @@ public class LangUtil {
 		return 21 <= vmVersion;
 	}
 
+	// AspectJ_JDK_Update
 	public static boolean is22VMOrGreater() {
 		return 22 <= vmVersion;
 	}