Community
Participate
Working Groups
+++ This bug was initially created as a clone of Bug #252794 +++ Projects should leverage only published APIs of dependencies. As a Release Review requirement, deviations should be listed as part of a migration plan, with bugs listed where APIs need to be provided by dependent projects.
Some thoughts about API in JWT: Should at least been marked as API and JavaDoc'd : * Metamodel * Interfaces or classes that must be extended by client plugins. For this bug, I'd like the opinion of Bull's contributors about what else they think has to be marked as API. Please note that marking a class/interface as API is something necessary to make the plug-in easily extensible; but on the other side, we won't be able to modify those classes often. (Changing API => Changing version => break compatibility with client extensions...)
I agree with you Mickael, at least, metamodel and interfaces or classes that must be extended by client plugins should be part of the API. We believe that care should be taken while considering JWT APIs since JWT is actually made of multiple parts (model, editor, monitoring, ...). For example, it would be perfectly acceptable (for us) to have one JWT-based product that uses the JWT model only (without the editor) and another one that uses the whole package (model, editor and monitoring). So APIs should not reference other APIs when it is not required (for example model API should not refer to editor's one). Of course extension points should be part of the API as well.
I've tried the PDE API Tools to understand concretely what is this "APIs" requirement, and concluded that * These tools are very powerful for release engineering and versioning, so that everybody should use them But... * Everything is about checking differences between two versions of a plugin. But since we currently are on an integration development stream, that does not make sense to think about versioning between 2 integration builds. So... * We have to wait for the next JWT release that we will consider as the "base" for API tools to check changes. This bug has to be postponed to next release and development stream. If it occurs later than the due-date (19th march), we'll advocacy to our PMC. This should not be a major issue, since no plugin or commercial product are currently built on JWT.
jwt-transformation-* projects have been modified for this requirement. The most efficient "methodology" I've used to find what is API and what is not: * Get the "target" plugin you want to change it your workspace * Get all direct client plugins in your workspace * Remove all export package from the "target" plugin MANIFEST.MF. * All client plug-ins will crash... Then reexport all packages that are necessary to get them building, but... * Each time you reexport a package ** If there are some classes that are in this package but that are clearly not API, you have 2 choices 1. Create an "internal" subpackage (that won't be exported), and put them into ot OR 2. Create an "api" package that will contain the classes and interfaces you'd like to export, and export this package ** And, obviously, add JavaDoc and "@since 0.6.0" tag on classes that are still in exported package, because they are classes that have external clients. I'll spend some time trying it on WE next week.
Created attachment 128736 [details] API internalization on WE This patch restricts exported packages and adds "@since 0.6.0" tag on all exported packages' classes (except classes that were generated ie model classes). Concretely: * All model interfaces are exported, but @since is not set since they are generated. * A few model impl and providers had to be exported for aspects and views. They were generated too, so that I did not tag them. * All figures are exported and tagged, since they are used by views extensions * All editParts for model element are exported and tagged, since they are used by views extensions * Some of the misc classes (GeneralHelpers...) and Preferences related classes are exported and tagged, since they are used by clients * The FactoryRegistry and related classes (Palette...) are exported and tagged * All classes referenced by extension points are exported and tagged. Some internal packages were created under exported packages for classes that are not use by clients plugins. Modifying all this code was another occasion to see that bug 248567 and bug 256134 are still very relevant and that they are naturally implied by JWT architecture. I've run locally the unit tests with this modification, and tested it manually designing a process, and did not experiment any regression. Then I request approval for commitment. Please not that it also affects other plugins, such as EPC view.
Hi Mickael, did you already commit the code (maybe on a branch)? In the current jwt-we I did not find any changes like internal packages or so. The changes that you describe would be okay in my opinion. Surely, we will need to adapt other plugins if the package structure is changed, but since this should go fast and we need the API freeze for Galileo M6, feel free to go ahead. I will afterwards adapt also the view plugins (like my EPC view).
I've made some more tests and still face some issues with figures. I'm working on it. By the way, I added an entry to the JWT Modification page to explain how to write code conforming to API tooling way: http://wiki.eclipse.org/JWT_Modifications#Hide_internal_package_and_leverage_API_analysis
Workflow editor conforms to this requirement. I thing that only aspect-related code is still to be done, and we can close this bug!
This bug cannot be totally fixed before M6+3. Indeed, Marc is not available until then, and he is the only one who is able to refactor all aspect related code without breaking anything. We will have to wait until next week before fixing it... However, this surely won't be a blocking point for our M6 build.
This *must* be fixed before tomorrow, so that we can build a M7 conform to requirement on wednesday.
API have been internalized or versionned on Conf Model. A new integration-build has been kicked and quickly tested, and no regression was found. Closing.
... I was the cause of the delay, much thanks to Mickael for fixing it nonetheless !
