Jump to: navigation, search

Sphinx/guidelines

Git Repository Layout

The source code will be in a single Git repository, organized in the following directories:

  • plugins: source code for all the plug-ins of Sphinx itself;
  • doc: the documentation plug-ins;
  • examples: example Sphinx modelers and sample metamodel definitions used by the examples and/or the tests;
  • tests: automated tests (JUnit);
  • features: feature definitions (including doc, examples and test features);
  • releng: parent project (for the root POM and shared files), target platform definitions, update-sites definitions;
  • tools: source code for development tools that contributors must install in their development environment. These are not part of Sphinx but are required to develop Sphinx.


General Rules About Code Organization

Modularity Criteria

The general criteria used to define the plug-ins boundaries are:

  • Core vs Eclipse-specific vs UI
    • Core code is pure library code with no dependency on any runtime framework (or maybe juste OSGi), and can be run headless and outside of an Eclipse runtime;
    • Eclipse-Specific code depends on the Eclipse framework, but not on the UI; it can still be run headless;
    • UI code requires a complete Eclipse Workbench (and provides the integration inside of it).
  • API vs internal API vs SPI vs internal (this is more for package boundaries than plug-in boundaries)
    • API is the official API that can be used by non-Sphinx code;
    • internal API is technically API (i.e. exported by the OSGi bundles) but reserved for internal usages inside of Sphinx itself. It can be used by non-Sphinx code but it does not have the same kind of guarantees in terms of backward compatibility;
    • SPI (Service Provider Interface) is specifically targeted for systems which want to extend Sphinx. This typically includes extension points and interface definitions that extender must implement. These may be used by Sphinx itself, for example to provide default implementations.
    • internal is all the rest, and is not accessible outside of Sphinx.

Note that these criteria should not dictate the final architecture, but simply allow a better control and understanding of the dependencies. Simply creating a bundle for each combination of these criterion and put each existing piece of code in the correct plug-in bucket would not result in any kind of meaningful architecture. However, the existing code base is more or less organized along such semi-technical boundaries and a good first step would be to ensure this structure is actually correctly enforced (this is not the case currently).

External Dependencies

In addition to other Eclipse projects, Sphinx depends on the following:

  • Java-SE 1.6.
  • Google Guava.
  • OSGi R4. Note that 99.9% of the code should be independent on OSGi APIs, but the plug-ins should be well-behaved OSGi bundles and some APIs will probably be exposed as OSGi service.

And for the automated tests:

  • JUnit 4 (the latest version included in Eclipse).

Automated Tests

The code for automated tests will be isolated in separate plug-ins, one or two for each Sirius plug-in. For example, say we have a Sphinx plug-in named org.eclipse.sphinx.emf. Its automated JUnit tests would be in org.eclipse.sphinx.tests.emf.

  • A Sphinx plug-in should export its internal packages with its own test plug-in(s) marked as x-friend.
  • Test plug-ins can share common code (custom asserts, setup helpers etc.) in plug-ins named org.eclipse.sphinx.testutil and org.eclipse.sphinx.testutil.integration.
  • A test plug-in can depend on:
    • the plug-in it tests (obviously);
    • JUnit, EasyMock and/or SWTbot;
    • any test support plug-in which does not add another dependency;
    • the dependencies of the plug-in it tests and their own test plug-ins;
    • example projects (in the examples directory of the Git repo) or even external projects like UML for its test fixtures.

Note: There may be limitations in the way Maven/Surefire/Tycho handle unit and integration tests which impact the way we organize test code.


New Plug-in Check List

  • appropriate copyright headers based on Sphinx copyright headers in Java source files, plugin.properties and plugin.xml.
  • no invalid UI dependencies. The non-UI plug-in does not depend on any UI plug-ins.
  • no imported packages. The required plug-ins are preferred than imported packages.
  • Java package name prefix equals plug-in name.
  • plug-in name/provider exported to plugin.properties.
  • plug-in provider is "Eclipse Sphinx".
  • appropriate plug-in versions. The current version is "0.8.0.qualifier".
  • presence of required legal files in plug-ins (about.html) and correctly checked build.properties.
  • Java 6 as minimum Java execution environment.
  • update of project settings.
  • appropriate EMF/EMF UI activator classes in internal package. The activator class is located in "internal" package. The actual implementation of UI activator extends EclipseUIPlugin, while that of the non-UI activator extends EclipsePlugin.
  • elimination of compiler warnings as far as possible, e.g., add missing @override annotations, externalize the strings, etc.


New Feature Check List

  • presence of license feature. The feature shares the license feature org.eclipse.sphinx.license.
  • feature name/provider/description exported to feature.properties.
  • feature provider is "Eclipse Sphinx".
  • appropriate feature versions. The current version is "0.8.0.qualifier".
  • presence of required legal files in features (license.html and epl-v10.html) and correctly checked build.properties.