Contributor guide

So you want your plugin to be included in Scala-IDE Ecosystems. Here is how to achieve that.

Finding a mentor

The plugin's owner writes an email to the Scala-IDE development mailing list to look for a mentor, making sure to provide the following information about the project:

• A link to the repository hosting the sources. It follows that your project should be open source, and available under a common open source license that in particular lets us redistribute it (e.g., Apache License 2.0, BSD License 2.0, Eclipse Public License, Scala License, or similar).

• A link to the plugin's documentation. At a minimum, the documentation should describe how to use the plugin and highlight its main features (screenshots warmly recommended).

• A link to the issue tracker that can be used to report bugs or feature requests.

• A link to the p2 repository to use for installing the plugin. Please, make sure to clearly state with what Scala IDE version your plugin should be installed. (Read the section about plugin versioning).

• A link to the project's website (optional).

All members of the Scala-IDE team can be mentors of a project.

Mentor duty

A mentor is responsible of ensuring that a plugin is ready for inclusion in the ecosystem. Specifically, a mentor reads the documentation and tries out the plugin to ensure that the plugin can be successfully installed with each supported version of the Scala IDE.

Mentors report to the project owner all problems they find related to either the plugin's behavior, its documentation, or anything else they consider important to fix before the plugin is included in the ecosystem. When a mentor is satisfied, he sends a follow-up email in the Scala-IDE development mailing list to notify the community that the plugin is ready for inclusion. At this point the mentor becomes the plugin's sponsor.

Ready for inclusion in the Ecosystem

A plugin that has a sponsor is ready for inclusion in the ecosystem. To do so, the project's owner provides the correct artifacts as outlined in the Contributor's cheatsheet. Once this is done, he creates a pull request (PR) against the Ecosystem repository. The PR's content is a single file, which will be referred to as the plugin definition, to be placed inside the features folder. The file's name has to match the plugin's feature id (you can find the feature id value in your plugin's feature.xml), and its content should conform to the documented grammar. Finally, in the PR description, make sure to add a review-by: @<sponsor-github-username>, where <sponsor-github-username> is the real GitHub username of the plugin's sponsor. The PR is ready to be merged only after the sponsor has given his approval.

A freshly included plugin will be made available in the ecosystem under the Incubation category. The different ecosystem’s categories are discussed next.

Ecosystem categories: Incubation vs. Stable

Plugins available in the ecosystem are listed in one of two categories: Incubation or Stable. Plugins' categories exist to set the right expectation on users: while plugins in Incubation can be yet not ready for wide adoption, Stable ones are expected to have matured to the point they can be safely used with no major headache.

As mentioned in the previous section, new plugins are always first made available under the Incubation category. To move from Incubation to Stable, a plugin has to meet the following requirements:

• The plugin is available for the latest released Scala IDE.
• The plugin is well documented.
• The plugin has good adoption, and happy users (e.g., new releases with critical fixes are made available in a timely manner).

A plugin listed in the Stable category is temporarily moved back to Incubation when no release of the plugin exist against the latest stable Scala IDE release. The plugin is moved back to the Stable category as soon as release of the plugin (for the latest stable Scala IDE) is made available.

Additionally, plugins can be permanently moved back to Incubation if the Scala-IDE team believes that one of the above described points has been neglected for too much time.

Exclusion from the Ecosystem

The main, and likely only one, reason for excluding a plugin from the ecosystem is instability. For instance, if a plugin turns out to be too immature, or if it is no longer actively maintained, then there is no real benefit for the community in keeping the plugin in the ecosystem. Hence, it will be removed.