Contributing to JetBrains MPS Project

Building MPS from Source

Please follow the instructions in the project README.md file to clone and build the project.

Building MPS from Source on the command line

In order to build MPS from source you need to download the IDEA IntelliJ community edition and open the MPS project in idea. To do so, call "Open Project" and choose the folder in which the git repository is located. After that, trigger a rebuild. Once the rebuild is finished, open a shell and navigate into the build directory. The script to execute is called run.build.sh (assuming you have ant installed).

Making the contribution

This section describes how you make changes to the source code.

• Now you should be ready to make your changes. Commit as frequently as you like.

• You should test your code by running the provided automated test suits. These can be run from IntelliJ IDEA: Run -> Run... In particular, the GlobalTestSuite, ModuleTestSuite and ProjectTest run configuration are to be used.

• There are no published code style guidelines at the moment. You may check out the MPS sources or drop us an email when in doubts.

Pushing your changes to us

This section explains how you can forward your local changes to JetBrains.

• Push your branch to your private GitHub repository: git push origin my_branch_name

• Make a pull request at GitHub - open your repository in a browser, make sure you are looking at the branch that you'd like to see pulled and click the Pull Request button in the upper right corner.

• We should process your request and you'll get notification about the progress through the standard GitHub facilities.

Keeping your fork current

As you change your code and commit, you make changes to your own fork of the MPS github repository. Using pull requests, you can make the MPS developers aware of your changes, and they may or may not integrate your change into the original repository. However, in the meantime, the original MPS repository changes (as a consequence of the MPS team working on the code), and your fork is not kept in sync. To keep your local clone and your remote fork in sync with the changes in the original repository, please do the following:

• In your local clone, add an additional remote that points to the original MPS github repository. git remote add mpsrepo https://github.com/JetBrains/MPS

• You can now pull the changes from the original repository by using git pull mpsrepo master

• If you develop your contribution on a branch as we suggested above, you'll have to merge the updated master into your branch using git merge master (while on your branch)

• As you do that, you will have to resolve possible merge conflicts locally.

• You can then push the merged changes to your own fork using git push origin (origin is the default name assigned to a remote by git clone).

Accessing MPS Git Repository

The main MPS repository is located at git://git.jetbrains.com/mps/mps.git and can be used as a base for submitting your patches to MPS. The process using GitHub should, however, be considered to be the preferred way. To check out from IntelliJ IDEA, select “Version Control | Checkout from Version Control | Git” from the main menu. In the “Git Repository URL” field, enter: git://git.jetbrains.org/mps/mps.git To check out from the command line, use the following command: git clone git://git.jetbrains.org/mps/mps.git In addition you can browse MPS sources using git web access.

The big division

MPS is being developed in both IntelliJ IDEA and MPS itself. So the code base consists of Java sources as well as MPS models. Whenever you open a Java file in IDEA, you can check whether the file contains a comment /*Generated by MPS */, which indicates, that the source was generated and the real source is to be found in MPS, most likely under a similar name. The shortcut Control/Cmd + N for opening files, classes and root nodes by name will certainly come in handy and luckily it is the same shortcut in both IDEA and MPS.

Structure

The Project View in MPS may give you rough guidelines on how the project is structured.

• core - as the name indicates, it holds the essential language-design functionality

  • aspects - holds the functionality and languages of the individual language definition aspects

  • baselanguage - holds the implementation of BaseLanguage and its extensions, such as closures, collections and other

  • languages - contains core languages, such as smodel, quotation, xml and others

  • stubs - stores loaded external libraries, such as JDK, Ant, the IntelliJ platform and the MPS Java sources

• platform - contains the IDE extension functionality, such as the console, vas support, model checking, build language, and other

• samples - groups the sample projects

• tests - contains tests for various aspects of MPS

• workbench - provides integration with the IntelliJ platform and implementation of many UI elements, supports execution and debugging

Committing your work

The MPS project stores generated artefacts in Git alongside the sources and models. Before committing please ensure that all the changed models have been regenerated - the (generation required) note must disappear. May you fail to do so, the TeamCity CI server will reject the commit by a failed build, since it checks all artefacts for being correctly generated. The best way to regenerate is to invoke Rebuild from the model's or module's context menu.

Adding productivity guide tips

When adding a new productivity guide tip, either for MPS itself or for a standalone MPS-based IDE, please follow the following guidelines:

• Create an html file describing the tip and place it in /workbench/resources_en/source/tips. Please follow the styles used by other tips.

• List your new html file in /workbench/resources_en/source/tips/tips.xml to make it part of the Tip of the day dialog

• Add a call to FeatureUsageTracker.getInstance().triggerFeatureUsed("my.key"); into the apropriate action to indicate use of the feature to the productivity guide, where my.key is an identifier for the productivity tip that you create or re-use.

• Add a display name to the key in /workbench/resources_en/source/messages/FeatureStatisticsBundle.proeprties

• Register a productivity guide entry in /workbench/resources/source/ProductivityFeaturesRegistry.xml mapping the id to the html page