CodeTools proposal: apidiff

Fri Jan 8 21:18:31 UTC 2021

Hi Gunnar,

Yes, I agree that some sort of JDK diff tool has been a long time 
coming, and yes, I have an advanced prototype that I hope to publish 
soon to a new GitHub repo under the "Code Tools" umbrella.

Although I'm not an expert on many of the existing tools, my 
understanding is that they typically just compare class files, or 
compare javadoc output. `apidiff` is different because it can leverage a 
combination of inputs, and because it uses the `javac` front end to read 
source and class files, the tool will be easier to keep current with the 
latest JDK enhancements, especially when those enhancements involve new 
language features, new class features and/or revisions to the 
javadoc-generated documentation files.

You are also correct that there has been an internal tool used to 
generate API diffs for JSR spec APIs. This proposal is related in the 
sense that the intent is to provide a public tool that can fulfill the 
same purpose. Indeed, this purpose is one of the reasons to support 
3-way comparisons, so that we can routinely create reports of 
differences in the current build against the previous build and the 
previous GA build. You can sometimes also see evidence of that internal 
tool in CSR requests, and that is another intended use case for the new 
tool.

-- Jon

On 1/8/21 1:01 PM, Gunnar Morling wrote:
> Hi Jonathan,
>
> That's a very interesting proposal, I've been missing some sort of API 
> diff tool in the JDK for a long time.
>
> It sounds as if you already have a version of this tool working; could 
> you perhaps share an example for the kind of report it generates? I'd 
> also be curious how this differs from existing tools like RevApi [1] 
> or JapiCmp [2] (which forms the basis of the AdoptOpenJDK JDK API Diff 
> Report [3]). There also used to be a tool internally at Oracle which 
> was (or maybe still is) used for generating API diffs for JSR spec 
> APIs, e.g. see [4]. Is this proposal somehow related to this tool?
>
> Thanks,
>
> --Gunnar
>
> [1] https://github.com/revapi/revapi 
> <https://urldefense.com/v3/__https://github.com/revapi/revapi__;!!GqivPVa7Brio!MdXbu0QiXIJuFxfExNGWPTSmT7JcoRxAOsFU3qYoA9Jq_bAHHePtm0ZnxpyjLqyFMRXWlw$>
> [2] https://github.com/siom79/japicmp 
> <https://urldefense.com/v3/__https://github.com/siom79/japicmp__;!!GqivPVa7Brio!MdXbu0QiXIJuFxfExNGWPTSmT7JcoRxAOsFU3qYoA9Jq_bAHHePtm0ZnxpyjLqymv4sq0g$>
> [3] https://github.com/AdoptOpenJDK/jdk-api-diff 
> <https://urldefense.com/v3/__https://github.com/AdoptOpenJDK/jdk-api-diff__;!!GqivPVa7Brio!MdXbu0QiXIJuFxfExNGWPTSmT7JcoRxAOsFU3qYoA9Jq_bAHHePtm0ZnxpyjLqxG-ORJ2w$>
> [4] https://cr.openjdk.java.net/~mr/jigsaw/spec/diff/index.html 
> <https://cr.openjdk.java.net/~mr/jigsaw/spec/diff/index.html>
>
>
> Am Fr., 8. Jan. 2021 um 19:57 Uhr schrieb Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>>:
>
>     On 1/8/21 10:48 AM, Jonathan Gibbons wrote:
>     > This is a proposal for a new tool in the OpenJDK CodeTools project:
>     > apidiff.
>     >
>     > I've attached Markdown and HTML versions of the proposal.
>     >
>     > -- Jon
>     >
>     >
>
>     I guess the attachments didn't make it.  Here's the Markdown:
>
>     # Proposal: apidiff
>
>     Summary: A utility to compare two or more versions of an API, using a
>     combination of the information in class files, source files and/or API
>     documentation files.
>
>     ## Rationale
>
>     An important task when evolving APIs is to be able to compare
>     different
>     versions
>     of an API, such as before and after a proposed change. However,
>     comparing
>     versions of an API is not an easy task:
>
>     * Comparing just source files is hard because of additional content
>     related to
>        the implementation of the API.
>
>     * Comparing just class files is hard because class files do not
>     include any
>        narrative specification from the documentation comments.
>
>     * Comparing just API documentation files is hard because the
>     underlying
>     model of
>        the API can be difficult to discern, and is subject to the
>     presentation by the
>        `javadoc` tool. However, this is the form most commonly used by
>     developers
>        wanting to read the specification of an API.
>
>     In addition, the Java language is [evolving][amber], with new
>     features like
>     [records][] and [sealed classes][], and it is desirable for
>     comparison
>     tools to
>     be able to handle such features when they show up in an API.
>
>     It would also be good to be able to classify changes with respect to
>     whether or
>     not they are compatible changes, and if so,  what
>     ["kind"][compatibility] of
>     compatible. However, this generally requires detailed and accurate
>     models of the
>     APIs being compared: more so than can reasonably be obtained from API
>     documentation files.
>
>     ## Description
>
>     `apidiff` is a tool that leverages the `javac` front end and other
>     code
>     in the
>     JDK `java.compiler` and `jdk.compiler` modules in order to read
>     source
>     and/or
>     class files, and to find the declarations to be compared. When source
>     files are
>     provided, the tool can also compare the "raw" documentation
>     comments for
>     those
>     declarations, and if the corresponding API documentation is provided,
>     the tool
>     can also extract and compare the parts of the documentation for those
>     declarations. Third-party libraries ([java-diff-utils][],
>     [daisydiff][]) are
>     used to compare the plain text of documentation comments and the
>     relevant parts
>     of the generated API documentation.
>
>     The tool can compare two or three versions of an API. It can
>     compare classes
>     on the class path, or in modules. It can also compare the
>     often-overlooked
>     specifications of the serialized forms of classes. It can compare
>     classes in
>     different versions of JDK, although there are currently limitations if
>     preview features are involved. The tool requires JDK 11 or newer
>     to run:
>     because it uses JDK modules internally, the tool must be run with
>     a version
>     of JDK at least as new as the newest API being compared.
>
>     When comparing more than two versions of an API, the "structural"
>     parts of
>     each declaration are compared and reported as a group; the
>     "narrative" parts
>     of the specification of each declaration are compared pair-wise
>     against the
>     latest version.
>
>     Internally, the tool comprises a front end, which can set up and
>     access
>     different concurrent instances of the `javac` front end and which
>     reports
>     differences via an interface to a back end, which can generate an
>     HTML
>     report.
>     An internal component provides the ability to extract the parts of
>     an API
>     documentation file containing the specifications of the
>     declarations in that
>     file, ignoring the "window dressing" of the header, footer, and
>     summary
>     tables;
>     this component can handle the output generated by most recent
>     versions
>     of the
>     `javadoc` tool.
>
>
>     [amber]: https://openjdk.java.net/projects/amber/
>     <https://openjdk.java.net/projects/amber/>
>     [records]: https://openjdk.java.net/jeps/395
>     <https://openjdk.java.net/jeps/395>
>     [sealed classes]: https://openjdk.java.net/jeps/360
>     <https://openjdk.java.net/jeps/360>
>     [compatibility]:
>     https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility
>     <https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility>
>     [binary compatible]:
>     https://docs.oracle.com/javase/specs/jls/se15/html/jls-13.html
>     <https://docs.oracle.com/javase/specs/jls/se15/html/jls-13.html>
>     [java-diff-utils]:
>     https://github.com/java-diff-utils/java-diff-utils
>     <https://urldefense.com/v3/__https://github.com/java-diff-utils/java-diff-utils__;!!GqivPVa7Brio!MdXbu0QiXIJuFxfExNGWPTSmT7JcoRxAOsFU3qYoA9Jq_bAHHePtm0ZnxpyjLqzY1cPANQ$>
>     [daisydiff]: https://code.google.com/archive/p/daisydiff/
>     <https://urldefense.com/v3/__https://code.google.com/archive/p/daisydiff/__;!!GqivPVa7Brio!MdXbu0QiXIJuFxfExNGWPTSmT7JcoRxAOsFU3qYoA9Jq_bAHHePtm0ZnxpyjLqxnYMlTfA$>
>
>
>