Papyrus/Papyrus Developer Guide/API Evolution Reports
API Evolution Report
The Developer Tools Build job on the Hudson server produces as one of its artifacts an API Evolution Report that shows in fine detail the changes in the public API as compared to the last release on the previous stream. So, for example, the changes in a Neon-stream (2.0) build as compared to the last release on the Mars stream (1.1.4).
The primary audience for these API Evolution Reports is the community of developers that extend Papyrus, building tools such as DSML editors, transformations, and the like on top of Papyrus. Not so much the developers working on the Papyrus project, itself. As such, it is the intent of the report format that it can easily be copied into the release notes for each published Papyrus release build (and probably milestone builds, also).
As the report is essentially a comparison of the public API exposed by plug-ins in two p2 repositories, it is conveniently integrated into a build that is based on the Papyrus Main build's output repository. The Developer Tools build is one such, with the extra advantage that this build produces the
org.eclipse.papyrus.bundles.tests JUnit test plug-in in which the report can be implemented, to be shared if necessary with test builds that may want to re-use it in whole or in part.
The implementation of the report is based on work by Eike Stepper in the CDO project. The
org.eclipse.papyrus.bundles.tests.apireport project contains the core reporting engine:
APIReportGenerator— compares the current PDE Target with the bundles found in some given location (usually a self-contained Eclipse installation or a p2 repository), emitting the API delta as an XML file
API2HTML— a simple SAX-based transformation of the report XML to HTML, as presented (with the support of a CSS stylesheet) in the Hudson build page
ReportFixture— a convenience for clients of the report generator to manage the input and output resources of a report, including copying the CSS and its images from the host bundle to the report output
The principle driver of the reporting engine is the
org.eclipse.papyrus.bundles.tests.APIReports class, which is structured as a JUnit test suite. This defines a pseudo-test
apiDeltaReport that produces an API Evolution Report based on three inputs, specified as system properties (because that is convenient for Maven build integration):
apireport.baseline— the path in the local filesystem to the Eclipse installation or p2 repository containing the bundles against which the target platform is compared
apireport.output— (optional) the base directory in which to generate the report, in a directory named
apireportswithin this output directory. If not specified, the current working directory is used as the output root
apireport.verbose— (optional) if specified with a
truevalue, provide more verbose tracing of the API delta comparison and report generation process