1 files changed, 112 insertions, 0 deletions
diff --git a/docs/devguide/compatibility.adoc b/docs/devguide/compatibility.adoc
new file mode 100644
index 000000000..63822e003
--- /dev/null
+++ b/docs/devguide/compatibility.adoc
@@ -0,0 +1,112 @@
+[[compatibility]]
+== AspectJ version compatibility
+
+[[versionCompatibility]]
+=== Version Compatibility
+
+Systems, code, and build tools change over time, often not in step.
+Generally, later versions of the build tools understand earlier versions
+of the code, but systems should include versions of the runtime used to
+build the AspectJ program.
+
+[[javaCompatibility]]
+==== Java compatibility
+
+AspectJ programs can run on any Java VM of the required version. The
+AspectJ tools produce Java bytecode .class files that run on Java
+compatible VM's. If a Java class is changed by an aspect, the resulting
+class is binary compatible (as defined in the Java Language
+Specification). Further, the AspectJ compiler and weaving do all the
+exception checking required of Java compilers by the Java
+specifications.
+
+Like other Java compilers, the AspectJ compiler can target particular
+Java versions. Obviously, code targeted at one version cannot be run in
+a VM of a lesser version. The `aspectjrt.jar` is designed to take
+advantage of features available in Java 2 or Java 5, but will run in a
+JDK 1.1.x environment, so you can use AspectJ to target older or
+restricted versions of Java. However, there may be restricted variants
+of JDK 1.1.x that do not have API's used by the AspectJ runtime. If you
+deploy to one of those, you can email aspectj-dev@eclipse.org or
+download the runtime code to modify it for your environment.
+
+Aside from the runtime, running the AspectJ tools themselves will
+require a more recent version of Java. You might use Java 5 to run the
+AspectJ compiler to produce code for Java 1.1.8.
+
+[[runtimeCompatibility]]
+==== Runtime library compatibility
+
+When deploying AspectJ programs, include on the classpath the classes,
+aspects, and the AspectJ runtime library (`aspectjrt.jar`). Use the
+version of the runtime that came with the tools used to build the
+program. If the runtime is earlier than the build tools used, it's very
+likely to fail. If the runtime is later than the build tools used, it's
+possible (but not guaranteed) that it will work.
+
+Given that, three scenarios cause problems. First, you deploy new
+aspects into an an existing system that already has aspects that were
+built with a different version. Second, the runtime is already deployed
+in your system and cannot be changed (e.g., some application servers put
+`aspectjrt.jar` on the bootclasspath). Third, you (unintentionally)
+deploy two versions of the runtime, and the one loaded by a parent
+loader is used).
+
+In earlier versions of AspectJ, these problems present in obscure ways
+(e.g., unable to resolve a class). In later versions, a stack trace
+might even specify that the runtime version is out of sync with an
+aspect. To find out if the runtime you deployed is the one actually
+being used, log the defining class loader for the aspects and runtime.
+
+[[binaryCompatibility]]
+==== Aspect binary compatibility
+
+Generally, binary aspects can be read by later versions of the weaver if
+the aspects were built by version 1.2.1 or later. (Some future weavers
+might have documented limitations in how far back they go.) If a
+post-1.2.1 weaver reads an aspect built by a later version, it will emit
+a message. If the weaver reads in a binary aspect and writes it out
+again, the result will be in the form produced by that weaver, not the
+original form of the aspect (just like other weaver output).
+
+With unreleased or development versions of the tools, there are no
+guarantees for binary compatibility, unless they are stated in the
+release notes. If you use aspects built with development versions of the
+weaver, be careful to rebuild and redeploy with the next released
+version.
+
+[[sourceCompatibility]]
+==== Aspect source compatibility
+
+Generally, AspectJ source files can be read by later versions of the
+compiler. Language features do not change in dot releases (e.g., from
+1.2.1 to 1.2.2). In some very rare cases, a language feature will no
+longer be supported or may change its meaning; these cases are
+documented in the release notes for that version. Some changes like this
+were necessary when moving to binary weaving in the 1.1 release, but at
+this time we don't anticipate more in the future. You might also find
+that the program behaves differently if you relied on behavior specific
+to that compiler/weaver, but which is not specified in the
+xref:../progguide/semantics.html[Semantics appendix to the Programming
+Guide].
+
+[[upgrading]]
+==== Problems when upgrading to new AspectJ versions
+
+Let's say your program behaves differently after being built with a new
+version of the AspectJ tools. It could be a bug that was introduced by
+the tools, but often it results from relying on behavior that was not
+guaranteed by the compiler. For example, the order of advice across two
+aspects is not guaranteed unless there is a precedence relationship
+between the aspects. If the program implicitly relies on a certain order
+that obtains in one compiler, it can fail when built with a different
+compiler.
+
+Another trap is deploying into the same system, when the `aspectjrt.jar`
+has not been changed accordingly.
+
+Finally, when updating to a version that has new language features,
+there is a temptation to change both the code and the tools at the same
+time. It's best to validate the old code with the new tools before
+updating the code to use new features. That distinguishes problems of
+new engineering from those of new semantics.