1 files changed, 109 insertions, 0 deletions
diff --git a/docs/release/README-1.9.20.adoc b/docs/release/README-1.9.20.adoc
new file mode 100644
index 000000000..51b9033e9
--- /dev/null
+++ b/docs/release/README-1.9.20.adoc
@@ -0,0 +1,109 @@
+== AspectJ 1.9.20.1
+
+_© Copyright 2023 Contributors. All rights reserved._
+
+_Release info: 1.9.20.1 available 04-Sep-2023_
+
+This is a bugfix release for 1.9.20, fixing two problems:
+
+* https://github.com/eclipse-aspectj/aspectj/issues/257[Regression bug 257] introduced in 1.9.20 would match negated
+  type patterns like `!void` or `!String[]` incorrectly.
+* https://github.com/spring-projects/spring-framework/issues/27761[Spring issue 27761] describes a problem where
+  AspectJ, when used by Spring AOP, in rare cases falsely considered bridge methods for overridden generic methods for
+  matching, leading to falsely negative matching results. See also
+  https://github.com/eclipse-aspectj/aspectj/issues/256[AspectJ tracker issue 256]).
+
+The list of issues addressed for 1.9.20.1 can be found
+https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[here].
+
+== AspectJ 1.9.20
+
+_© Copyright 2023 Contributors. All rights reserved._
+
+_Release info: 1.9.20 available 16-Aug-2023_
+
+Please note that Bugzilla for issue management is deprecated and new issues should be filed as
+https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The list of issues addressed for 1.9.20 can be found
+here:
+
+* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20[GitHub 1.9.20]
+* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[GitHub 1.9.20.1]
+* 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]
+
+=== New features
+
+AspectJ 1.9.20 supports https://openjdk.java.net/projects/jdk/20/[Java 20] and its final, preview and incubator
+features, such as:
+
+* Record patterns (preview)
+* Virtual threads (preview)
+* Pattern matching for `switch` (preview 3)
+* Structured concurrency (incubator)
+
+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
+https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940[this comment]. AJC therefore inherits the same
+problems for the specific cases described in the linked issues.
+
+=== Improvements
+
+* 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 *require you to recompile your aspects and projects/classes using them.*
+  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.
+* Along with fixing https://github.com/eclipse-aspectj/aspectj/issues/24[GitHub bug 24], the syntax for array type
+  matching has been improved considerably. You can find some examples
+  https://github.com/eclipse-aspectj/aspectj/tree/master/tests/bugs1920/github_24[here].
+
+=== Code examples
+
+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):
+
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17[Pattern matching for switch (preview 1)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features199/java18[Pattern matching for switch (preview 2)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features1919/java19[Pattern matching for switch (preview 3),
+  record patterns (preview 1)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features1920/java20[Pattern matching for switch (preview 4),
+  record patterns (preview 2)]
+* 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.
+
+=== Other changes and bug fixes
+
+* 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.
+
+=== AspectJ usage hints
+
+==== AspectJ compiler build system requirements
+
+Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` 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 `aspectjrt`, but the
+compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
+weaver `aspectjweaver` still only require JRE 8+.
+
+==== Use LTW on Java 16+
+
+Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
+https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set
+the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` 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.
+
+==== Compile with Java preview features
+
+For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
+`java --enable-preview` on that JDK.
+
+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.