Revision as of 12:54, 8 December 2020

The Trace Compass Incubator is a project that contains additional features:

• That are under development, but still usable enough to be used and tested by users.
• Whose content relates to a specific trace type or domain of analysis (for example virtual machine analyses) and that no other plugin will depend on.

This project is a permanent incubator, ie the features will never be officially released with a specific version, hence, nothing will be API in the plugins developed there. Some feature may eventually graduate to the Trace Compass project itself if required, for example if many other features depend on them or they provide an interesting functionality for the core Trace Compass.

Getting started

So, you have a new feature to propose. First follow the Trace Compass Development Environment Setup guide. The sources section contains the git repository for the incubator. Make sure to clone it and add the plugins to the workspace.

In the source tree, there is a helper script that will create the necessary plugins for a new feature, including feature, ui, unit tests and documentation plugins.

$ cd org.eclipse.tracecompass.incubator
$ skeleton/create_new_feature.py -h  
  This will display the help message for the script with the available arguments
$ skeleton/create_new_feature.py --dir tracetypes --copyright "École Polytechnique de Montréal" "My Awesome Tracetype"

This last command will create 6 plugins in directory tracetypes named org.eclipse.tracecompass.incubator.my.awesome.tracetype with the Activators initialized, the pom.xml files already populated, etc. You are now ready to import those plugins in Eclipse and start developing.

Contributing a feature/patch

Read the documentation on how to contribute to prepare to push your contribution.

The only difference is that the remote to push to gerrit is

[remote "eclipse-review"]
	url = ssh://<username>@git.eclipse.org:29418/tracecompass.incubator/org.eclipse.tracecompass.incubator.git
	push = HEAD:refs/for/master

This will send the patch to gerrit, where it will be timely reviewed by a member of the community

Review guidelines

For new features, the review of two committers is necessary. The patch will not be reviewed in details. Some comments may be done on the code style, but they are not in themselves reasons for rejection of a patch. What will be verified:

• Does the feature work and integrate well with Trace Compass
• Does it seem stable enough (no obvious race conditions or UI freeze when simply playing around)
• Is there a minimal documentation to help the reviewer test and evaluate the feature. If adding a new trace type or analysis without providing a link to a trace to test it on, it will be hard to review.
• Are there some unit tests. Though not mandatory for a first pass on the feature, it is highly advised to have some basic unit tests, to help the maintainability

Incubator committers

Since the incubator is meant to receive a lot of patches for different domains/trace types, not all committers are expected to know/maintain the full code base. Someone contributing a new feature will thus gain committers status quite rapidly once the feature is merged and is expected to be the official maintainer of that part of the code, hence should do the reviews on those plugins or at least make sure that the code does not go unmaintained and patches slip in the cracks.

Publishing a feature

The script mentioned in the first section will create the plugins, but it will not publish it on the incubator update site. Some additional steps are required.

Prepare the feature

First the feature plugins needs to be made ready with the proper dependencies, especially if some of those are themselves part of the incubator. The feature plugin is the one with no suffix. In the example above it would be org.eclipse.tracecompass.incubator.my.awesome.tracetype.

• Open the feature.xml file in that plugin to open the feature editor.
  • In the Included plugins tab, make sure all the plugins that will be part of the feature are there. They are usually the .core, .ui and .doc.user plugins, the unit tests are not included.
  • In the Dependencies tab, click on the Compute button next to the list box on the left. This will list all the plugins that are necessary for the plugins of this feature to work.
• Open the feature.properties file
  • Edit the properties as you want to see them in the update site

Add it to the update site

The project containing the update site content is org.eclipse.tracecompass.incubator.releng-site.

• Open the category.xml file
  • You can now add your feature under the corresponding category or create a new category if necessary.

Note for maintainers: Handling releases