Contributing to JetBrains MPS Project

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

Alternatively, MPS can be built from the source by using the command line.

Before you start, make sure you have Ant installed. Download IntelliJ IDEA Community Edition and open the MPS project in it. To do so, click "Open Project" and choose the folder the Git repository is located in. After that, trigger a rebuild. Once the rebuild is finished, open a shell, navigate to the build directory, and run run.build.sh.

Now you should be ready to make your changes. Here are a couple of guidelines about how to do that:

• Feel free to commit as frequently as you like.

• Make sure to test your code by running the provided automated test suites. To do so, in IntelliJ IDEA select Run -> Run... We strongly recommend running the GlobalTestSuite, ModuleTestSuite, and ProjectTest run configurations, in particular.

• There are no published code-style guidelines at the moment. You can check out the MPS sources or post in the #contributors channel when in doubt.

Here’s how you can forward your local changes to JetBrains:

• Push your branch to your private GitHub repository by running the command git push origin my_branch_name

• Make a pull request on GitHub. To do so, open your repository in a browser, make sure you are looking at the branch that you want to pull, and then click the Pull Request button in the top right-hand corner.

• We’ll process your request and send you a notification about the progress through the standard GitHub facilities.

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 will change (as a consequence of the MPS team working on the code), and your fork will go out of sync.

To keep your local clone and your remote fork in sync with the changes in the original repository, you’ll need to pull from the original, resolve any conflicts, and then push to your fork. Follow these steps:

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

• Pull the changes from the original repository by using git pull mpsrepo master

• If you develop your contribution to 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 any merge conflicts locally.

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

The GitHub process described above is the preferred way to access the main MPS repository. However, it is also possible to use the MPS repository located at git://git.jetbrains.com/mps/mps.git as a base for submitting your patches to MPS.

To check out from IntelliJ IDEA, use the following repository URL:

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 the MPS sources using Git’s web access.

MPS is being developed in both IntelliJ IDEA and MPS itself, so the code base consists of Java sources and MPS models. Whenever you open a Java file in IntelliJ IDEA, you can check whether the file contains a /*Generated by MPS */ comment. This would indicate that the source was generated and the real source is to be found in MPS, likely under a similar name. The shortcut Cmd+O on Mac or Ctrl + N on Windows is used to open files, classes, and root nodes by name, and will certainly come in handy. Luckily, the key combination is the same in both IntelliJ IDEA and MPS.

The Project View in MPS may give you a rough guideline on how the project is structured:

• core holds the essential language-design functionality:

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

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

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

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

• samples groups the sample projects.

• tests contains tests for various aspects of MPS.

• workbench provides integration with the IntelliJ Platform and the implementation of many UI elements, and it supports execution and debugging.

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

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

• Create an HTML file describing the tip and place it in /workbench/resources_en/source/tips. Please follow the style used in the 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 an appropriate action to indicate that the feature is used in the productivity guide (where my.key is the identifier for the productivity tip that you’re creating or reusing).

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

• Register a productivity guide entry in /workbench/resources/source/ProductivityFeaturesRegistry.xml and mapp the id to the HTML page.