Add 1.9.20 release notes and update version compatibility matrix

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
author: Alexander Kriegisch <Alexander@Kriegisch.name> 2023-08-16 10:36:33 +0700
committer: Alexander Kriegisch <Alexander@Kriegisch.name> 2023-08-16 10:36:33 +0700
commit: 7c4d697add8f8d82323bd89f1b091b9128e76000 (patch)
tree: 7f2dafc6d86575559aa2e490fd578487693ab7a8 /docs
parent: 565f37b1970268234d9a823e2631ba3ed3e03037 (diff)
download: aspectj-7c4d697add8f8d82323bd89f1b091b9128e76000.tar.gz
aspectj-7c4d697add8f8d82323bd89f1b091b9128e76000.zip
3 files changed, 157 insertions, 0 deletions
diff --git a/docs/dist/doc/JavaVersionCompatibility.md b/docs/dist/doc/JavaVersionCompatibility.md
index 4d94a339d..ccec7742f 100644
--- a/docs/dist/doc/JavaVersionCompatibility.md
+++ b/docs/dist/doc/JavaVersionCompatibility.md
@@ -7,6 +7,7 @@ be easily concluded from the AspectJ version number anymore, and we are sorry fo
 
 AspectJ version | Java version | Comments
 ----------------|--------------|--------
+1.9.20 | 20
 1.9.19 | 19
 1.9.9 - 1.9.9.1 | 18
 1.9.8 | 17 | AspectJ compiler requires JDK 11+ during build time. During runtime, AspectJ still only requires Java 8+ for both compile-time and load-time weaving. Pure Java code can be compiled down to as old as 1.3 byte code level.
diff --git a/docs/dist/doc/README-1920.html b/docs/dist/doc/README-1920.html
new file mode 100644
index 000000000..7fcc33269
--- /dev/null
+++ b/docs/dist/doc/README-1920.html
@@ -0,0 +1,155 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+
+<head>
+<title>AspectJ 1.9.20 Readme</title>
+<style type="text/css">
+  <!--
+  P   { margin-left:  20px; }
+  PRE { margin-left:  20px; }
+  LI  { margin-left:  20px; }
+  H4  { margin-left:  20px; }
+  H3  { margin-left:  10px; }
+  -->
+</style>
+</head>
+
+<body>
+<div align="right"><small>&copy; Copyright 2023 Contributors. All rights reserved.</small></div>
+
+<h1>AspectJ 1.9.20</h1>
+
+<p>
+  Please note that Bugzilla for issue management is deprecated and new issues should be filed as
+  <a href="https://github.com/eclipse/org.aspectj/issues/new">GitHub issues</a>.
+  The list of issues addressed for 1.9.20 can be found here:
+  <ul>
+    <li><a href="https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20">GitHub 1.9.20</a></li>
+    <li><a href="https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.20">Bugzilla 1.9.20</a></li>
+  </ul>
+</p>
+
+<h2>New features</h2>
+
+<p>
+  AspectJ 1.9.20 supports <a href="https://openjdk.java.net/projects/jdk/20/">Java 20</a> and its final, preview and
+  incubator features, such as:
+</p>
+<ul>
+  <li>Record patterns (preview)</li>
+  <li>Virtual threads (preview)</li>
+  <li>Pattern matching for <tt>switch</tt> (preview 3)</li>
+  <li>Structured concurrency (incubator)</li>
+</ul>
+
+<p>
+  Please note that the upstream Eclipse Java Compiler (ECJ) which the AspectJ Compiler (AJC) is a fork of still has some
+  open issues concerning Java 20 preview feature support, see the list in
+  <a href="https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940">this comment</a>. AJC therefore
+  inherits the same problems for the specific cases described in the linked issues.
+</p>
+
+<h2>Improvements</h2>
+
+<ul>
+  <li>
+      Since Java 9 and the introduction of the Java Module System, the upstream Eclipse Java Compiler (ECJ) and Eclipse
+      Java Development Tools (JDT) had gone through some internal changes, enabling both the compiler and the IDE to
+      handle new Java language features. In AspectJ, some of those internal changes have not been properly upgraded for
+      quite a while, but this is now fixed. However, it might <b>require you to recompile your aspects and
+      projects/classes using them.</b> Otherwise, you might get problems in Eclipse IDE or under certain circumstances
+      even when running newly compiled aspects in older AspectJ versions and vice versa. You are on the safe side if you
+      simply rebuild your projects. We are sorry for the inconvenience, but we have to follow upstream ECJ and JDT
+      changes.
+  </li>
+</ul>
+
+<h2>Code examples</h2>
+
+<p>
+  You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features
+  were first supported (possibly as JVM preview features):
+</p>
+<ul>
+  <li>
+    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17">
+      Pattern matching for switch (preview 1)
+    </a>
+  </li>
+  <li>
+    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features199/java18">
+      Pattern matching for switch (preview 2)
+    </a>
+  </li>
+  <li>
+    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features1919/java19">
+      Pattern matching for switch (preview 3), record patterns (preview 1)
+    </a>
+  </li>
+  <li>
+    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features1920/java20">
+      Pattern matching for switch (preview 4), record patterns (preview 2)
+    </a>
+  </li>
+  <li>
+    Please note that presently there is no specific sample code for virtual threads and structured concurrency in the
+    AspectJ code base, because these are just new APIs, no Java language features. You can find sample code for these
+    concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently
+    like any other Java API.
+  </li>
+</ul>
+
+<h2>Other changes and bug fixes</h2>
+
+<ul>
+  <li>
+    About a dozen bugs have been fixed, some of them quite old. See "list of issues addressed" further above and follow
+    the link to GitHub to find out if your issue is among them.
+  </li>
+</ul>
+
+<h2>AspectJ usage hints</h2>
+
+<h3>AspectJ compiler build system requirements</h3>
+
+<p>
+  Since 1.9.7, the AspectJ compiler <tt>ajc</tt> (contained in the <tt>aspectjtools</tt> library) no longer works on
+  JDKs 8 to 10. The minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler
+  (subset of JDT Core), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3
+  when compiling plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime
+  <tt>aspectjrt</tt>, but the compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime
+  <tt>aspectjrt</tt> and the load-time weaver <tt>aspectjweaver</tt> still only require JRE 8+.
+</p>
+
+<h3>Use LTW on Java 16+</h3>
+
+<p>
+  Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
+  <a href="https://openjdk.java.net/jeps/396">JEP 396 (Strongly Encapsulate JDK Internals by Default)</a> and related
+  subsequent JEPs. Therefore, you need to set the JVM parameter <tt>--add-opens java.base/java.lang=ALL-UNNAMED</tt> in
+  order to enable aspect weaving. This is due to the fact that the weaver uses internal APIs for which we have not found
+  an adequate replacement yet when defining classes in different classloaders.
+</p>
+
+<h3>Compile with Java preview features</h3>
+
+<p>
+  For features marked as preview on a given JDK, you need to compile with <tt>ajc --enable-preview</tt> and run with
+  <tt>java --enable-preview</tt> on that JDK.
+</p>
+<p>
+  Please note that you cannot run code compiled with preview features on any other JDK than the one used for
+  compilation. For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This
+  is a JVM limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16.
+  You still need to recompile, no matter what.
+</p>
+
+<hr>
+
+<p>
+  <b>Available:</b> 1.9.20 on 27###-Mar-2023
+</p>
+
+</body>
+
+</html>
diff --git a/docs/dist/doc/index.html b/docs/dist/doc/index.html
index 84d4f79ad..af2d945e0 100644
--- a/docs/dist/doc/index.html
+++ b/docs/dist/doc/index.html
@@ -136,6 +136,7 @@
 <tr> <td>README's
      </td>
      <td>Changes and porting guide for AspectJ
+        <a href="README-1920.html">1.9.20</a>,
         <a href="README-1919.html">1.9.19</a>,
         <a href="README-199.html">1.9.9 and 1.9.9.1</a>,
         <a href="README-198.html">1.9.8</a>,
author	Alexander Kriegisch <Alexander@Kriegisch.name>	2023-08-16 10:36:33 +0700
committer	Alexander Kriegisch <Alexander@Kriegisch.name>	2023-08-16 10:36:33 +0700
commit	7c4d697add8f8d82323bd89f1b091b9128e76000 (patch)
tree	7f2dafc6d86575559aa2e490fd578487693ab7a8 /docs
parent	565f37b1970268234d9a823e2631ba3ed3e03037 (diff)
download	aspectj-7c4d697add8f8d82323bd89f1b091b9128e76000.tar.gz aspectj-7c4d697add8f8d82323bd89f1b091b9128e76000.zip