Adding a new MPS Extension

If you want to add a new (or earlier developed existing) extension to MPS Extensions, the guidelines described here should help you. Note: the process of adding a new plugin is very similar to the process of migrating (which is very well-documented). This text repeats some of these steps less rigorously and adds all the steps needed for a new plugin. Note2: if you add a new extension, all this extension's code will be licensed under Apache 2.0 license.

Check if a new extension is really needed

If you have functionality that may already fit well under an existing extension, consider merging your extension's functionality into that existing extension. If the functionality of the extension you want to add doesn't fit under any of the existing extensions, and you know well where and how you want to add the extension, you can just open a pull request that adds your new extension (but please observe the checklist). If you are unsure how or where to start, you can open an issue and discuss/ask via that issue.

Checklist for adding a new extension

This checklist explains what you have to do to add a new extension fully and properly to the MPS Extensions.

Copy your extension into the repository and add to the MPS project

We assume that you have developed the extension you want to add in its own MPS Project. If not, you should first isolate it and make sure that it can work by itself. If your extension has dependencies to one of the plugins in MPS Extensions, you could either get this dependency from a Maven repository (like Itemis Nexus) or develop the extension in its entirety in a fork of MPS Extensions. If you want to develop your extension from scratch in a fork, you can just skip this section and add the (plugin) solution(s) and/or language(s) that comprise your extension directly to the MPS project that lives under the code folder.

Before you start, make sure that you have clean MPS models (without any classes_gen and source_gen folders). To copy or start your extension in the right place in the repository: * Create a subfolder with the name of your extension under the code directory: code/<extension_name>, e.g. code/plaintextgen for the already existing plaintextgen extension and copy the folders languages (if any) and solutions (if any) of your new extension to code/<name>. See section Move the Files under migration for more detailed instructions. * Open the MPS project living under the code folder, add the languages and solutions of your extension to it, and group all the added solutions and/or languages in a virtual folder that has the name of your extension. See section Adding the Files to the Project of migration for more detailed instructions. * In order to have proper license information in a custom version of MPS with the MPS Extensions included (soon to be downloadable from the JetBrains MPS site), add an about.txt file under the root of your extension's folder (similar like the plaintextgen has an about.txt under code/plaintextgen/about.txt). If your extension doesn't depend on any external software, you can indicate that in the about.txt (see the example of plaintextgen). If you are using third-party libraries or other software, the about.txt must attribute the licenses of this third-party software (an example of such attribution can be found in the about.txt of MPS itself).

Add to build solution

This step is needed so that your extension is built into a plugin and deployed to Maven repositories (like Itemis Nexus or mbeddr github packages), the JetBrains plugin repository, and the MPS download with MPS Extensions included. Detailed instructions can be found in section Adding it to the Build of migrating, but below are some extra steps you need to observe with a new extension:

Make a pull request

Please refer of section Sending the Pull Request of migrating for detailed instructions, but skip the last part about the migration label.

Manually upload a build of your extension's plugin(s) to the JetBrains plugin repository

Because the upload of a new plugin to the JetBrains plugin repository has a manual quality check step, you need to upload the plugin(s) of your extension the first time manually. After you have done this, an automated deployment process at JetBrains will completely take care of automatic deployment of new versions (upon migration to newer MPS versions) to the plugin repository. To manually upload your plugin(s) (assuming that you have executed the ./gradlew (or gradlew.bat) build step as part of integrating into the build as instructed in the previous section), do the following: * Edit the plugin.xml(s) of your plugin(s) artifact(s) (e.g. for plaintextgen that is artifacts/de.itemis.mps.extensions/com.dslfoundry.plaintextgen/META-INF/plugin.xml) to include idea_version: add a tag to the plugin.xml(s) that reads: <idea-version since-build="$current_mps_build" until-build="$next_mps_build" />, where $current_mps_build and $next_mps_build are formatted based on the MPS version: if your MPS version is LCDY.V.S (where L=millennium, C=century, D=decade, Y=year, V=major version in year, and S=minor version), then the build is DYV.S. So for MPS 2021.1.1, the idea_version tag would look as follows: <idea-version since-build="211.1" until-build="212.1" />