Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Papyrus/Papyrus Developer Guide/API Evolution Reports

< Papyrus‎ | Papyrus Developer Guide
Revision as of 14:54, 5 April 2016 by Give.a.damus.gmail.com (Talk | contribs) (Created page with "== API Evolution Report == The [https://hudson.eclipse.org/papyrus/job/Papyrus-Master-Developer/ Developer Tools Build] job on the Hudson server produces as one of its artifa...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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).

Audience

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).

Implementation

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.

Reporting Engine

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

Report Driver

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 apireports within this output directory. If not specified, the current working directory is used as the output root
  • apireport.verbose — (optional) if specified with a true value, provide more verbose tracing of the API delta comparison and report generation process

Back to the top