Analyze Spring Framework 3.2 backward compatibility with JDiff [SPR-9957]

[spring-projects-issues]

Chris Beams opened SPR-9957 and commented

Phil, would you be interested in doing the CLIRR analysis this time around (as done for 3.1 in #12767)?

The purpose here is twofold:

1. to help us make sure we haven't introduced any unintended public API compatibility issues
2. to serve as a resource linkable from the 3.2 migration guide to give users a detailed view of what's changed at the API level.

Attached are what few notes I took on how I generated the report previously, hopefully they are of some help.

Also, any ideas you have about streamlining or automating this process are welcome. It's not highly important as we typically need do this only once per major release, but would of course be nice.

---

Attachments:

• clirr-howto.txt (2.36 kB)

Issue Links:

• Analyze structure for cycles in preparation for 3.2 RC2 [SPR-9958] #14591 Analyze structure for cycles in preparation for 3.2 RC2
• Analyze Spring Framework 3.1 backward compatibility with CLIRR [SPR-8113] #12767 Analyze Spring Framework 3.1 backward compatibility with CLIRR

Referenced from: commits 631f24b

[spring-projects-issues]

Chris Beams commented

commit 631f24bb3284883f79cfde3d14676e5706a3ccfa
Author: Chris Beams <cbeams@vmware.com>
Commit: Chris Beams <cbeams@vmware.com>

    Introduce jdiff Gradle task
    
    The new jdiff task generates a report of API differences between the
    current version (i.e. the value of `version` in gradle.properties) and
    any older version of the framework, as specified by -DOLD_VERSION at
    the command line, or defaulting to `previousVersion` in
    gradle.properties.
    
    Running the command requires a separate clone directory pinned to the
    desired old version, as specified by -DOLD_VERSION_ROOT at the command
    line. This creates challenges from a build automation perspective,
    largely because Gradle doesn't (yet) have APIs for working with Git.
    
    This task may be further automated and included in nightly CI runs, but
    in the meantime, a number of reports back to 3.1.3.RELEASE have been
    generated manually and uploaded to [1], where one can now find the
    following entries in the directory listing:
    
     - 3.1.3.RELEASE_to_3.2.0.RC1
     - 3.2.0.M1_to_3.2.0.M2
     - 3.2.0.M2_to_3.2.0.RC1
     - 3.2.0.RC1_to_3.2.0.BUILD-SNAPSHOT
    
    Ideally, the final entry there would be kept up-to-date on a daily
    basis - again we may revisit doing so in the future. Going forward,
    reports will be generated and uploaded manually on an as needed basis
    and as part of the release process.
    
    The goal of these reports are as follows:
    
     - to ease the process of ensuring backward compatibility
    
     - to aid in code reviews, particularly when reviewing large pull
       requests
    
     - to ease the process of creating migration guides for project
       maintainers, i.e. to help us remember what's changed
    
     - to allow ambitious end-users to discover what's been changing at the
       API level without without needing to wait for detailed "what's new in
       version X" and/or migration guide documentation
    
    See documentation in jdiff.gradle for usage details.
    
    Note that the jdiff-1.1.1 distribution as downloaded from [2] has been
    added wholesale to the source tree under gradle/jdiff instead of
    uploading JDiff jars to repo.springsource.org as we would normally do.
    This is due to some unfortunate limitations in the implementation of the
    jdiff ant task that require a phisical JDIFF_HOME directory. Checking in
    the jars and various resources represents the simplest and most
    pragmatic solution to this problem, though ambitious contributors are
    free to do what's necessary to arrive at a more elegant arrangement.
    
    [1]: http://static.springframework.org/spring-framework/docs
    [2]: http://sourceforge.net/projects/javadiff/files/latest/download
    
    Issue: SPR-9957

[spring-projects-issues]

Chris Beams commented

Juergen, per my previous comment, the new JDiff reports should be a big help in actually doing the analysis, e.g.

• http://static.springsource.org/spring-framework/docs/3.1.3.RELEASE_to_3.2.0.RC1
• http://static.springsource.org/spring-framework/docs/3.2.0.RC1_to_3.2.0.BUILD-SNAPSHOT

I could even roll and publish an all-inclusive 3.1.3.RELEASE_to_3.2.0.BUILD-SNAPSHOT if it would be helpful to you. See the whole list of available reports at http://static.springsource.org/spring-framework/docs.

[spring-projects-issues]

Rossen Stoyanchev commented

Very useful indeed. The changes include documentation changes, which is very useful but too much detail if one wants to focus on API and compatibility changes.

[spring-projects-issues]

Chris Beams commented

The doc changes can be switched off. Thought I'd leave them in place for the time being to see what everyone thinks is most useful.