View source for Trace Compass/Incubator Guidelines

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 | 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 [[Trace_Compass/Contributor_Guidelines | documentation on how to contribute]] to prepare to push your contribution.

The only difference is that the remote to push to gerrit is
<pre>
[remote "eclipse-review"]
	url = ssh://<username>@git.eclipse.org:29418/tracecompass.incubator/org.eclipse.tracecompass.incubator.git
	push = HEAD:refs/for/master
</pre>

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.

= UX concerns =

Some minor things to remember when making new UIs is to remember that a human needs to operate them. Here are some minor guidelines to help out:

# The amount of time needed to click an item is directly proportional to the distance of the item and inversely proportional to the size of the item. So making a user hunt for an item like "Where's Waldo(tm)" will typically decrease engagement. (Fitt's law)
# The amount of notions a user can juggle at once is typically seven, plus or minus two. This means a view should not have more than 5 metrics shown at once. (Miller's law)
# People will "fill in the blanks" so we half create what we perceive. In terms of views, this means data shown needs to be unambiguous. e.g. don't mix light green and regular green to mean different things, try using secondary contrasting colors, don't use circle and square annotations together, use crosses and circles. Also, putting up too much visual data at once that is orthogonal may lead to invalid correlations. (Wordsworth)
# Users using tracing are often frustrated they got to this point and may make some irrational decisions. Guiding the user is always a good thing. (Behavioural economics)
# Have fun and be creative, we want to incubate great new ideas.

= Note for maintainers = 
[[Trace_Compass/Incubator/Handling releases]]