Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
spring-projects-issues opened this issue Nov 5, 2012 · 4 comments
Assignees
Labels
type: task A general task
Milestone

Comments

@spring-projects-issues
Copy link
Collaborator

spring-projects-issues commented Nov 5, 2012

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:

Issue Links:

Referenced from: commits 631f24b

@spring-projects-issues
Copy link
Collaborator Author

spring-projects-issues commented Nov 22, 2012

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
Copy link
Collaborator Author

spring-projects-issues commented Nov 22, 2012

Chris Beams commented

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

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
Copy link
Collaborator Author

spring-projects-issues commented Nov 22, 2012

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
Copy link
Collaborator Author

spring-projects-issues commented Nov 22, 2012

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: task A general task
Projects
None yet
Development

No branches or pull requests

2 participants