Contributing to JetBrains MPS Project
File a Bug Report
Reporting bugs is the most straightforward way to get involved. Bug reports take little time to file and are very helpful to developers. When you discover a problem, please report it to the JetBrains MPS issue tracker.
Make sure to provide information about your environment (OS, JDK, and MPS version), steps to reproduce the issue, and a description of the problem. As you are creating a new issue, the tracker will list similar existing issues – please review them to avoid duplicate issues. Feel free to upvote current issues.
Create Unit Test reproducing the problem
Most bugs can be reproduced or checked by automated JUnit tests. It's much easier and faster for our team to reproduce the bug by running a test case instead of manually going through a list of steps to reproduce the bug. If you could spare a few minutes to create a JUnit test that reproduces your problem, we will likely be able to process your report and fix the bug faster. Our team would really appreciate this.
Before starting to contribute to MPS, we need you to sign our Contributor License Agreement (CLA) electronically. Please fill out this form, and we will send you the agreement to sign via DocuSign.
Please create a pull request to the MPS GitHub repository to contribute your code. Branch off your code from the
master branch or a specific release branch (such as 2028.3).
If you want to help but don’t know how to go about it, please consult our list of nice-to-have simple features on our issue tracker with the contribution tag. Paste the link of your pull request as a comment on the issue. A member of the MPS development team will then review your patch or pull request. If it meets the quality criteria and fits with the rest of the code, your patch will be accepted and you'll receive a notification. Patches with a unit test attached are typically processed faster.
You can also propose a fix or feature by filing a new issue with a detailed description and pasting a pull request link.
If you have any questions, feel free to email us or post in the #contributors channel in our Slack workspace.
How to work with MPS sources
Although the main Git repository is located at JetBrains (see the
Accessing MPS Git Repository section below), we keep a public mirror on GitHub. The mirror is primarily meant to be an easy-to-use repository for external contributors. Here's how you can make a contribution to MPS through GitHub.
Building MPS from source
Please follow the instructions in the project README.md file to clone and build the project.
Build MPS from the source by using the command line
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 on "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.
Make a contribution
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
ProjectTestrun 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.
Push your changes
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 Requestbutton in the top right-hand corner.
We’ll process your request and send you a notification about the progress through the standard GitHub facilities.
Keep 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 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).
Accessing the MPS Git Repository
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:
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.
The project structure
Admittedly, the overall project structure can be complicated to see from the hierarchy of modules and packages in IntelliJ IDEA and MPS. You'll likely have difficulty understanding how the pieces fit together at first. We've collected a few pointers below to help you get started. If you have any additional questions, please contact us by email or through the #contributors Slack channel.
The big division
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,
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.
Committing your work
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.
Tips for developers
Adding productivity guide tips
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.xmlto 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
Register a productivity guide entry in
/workbench/resources/source/ProductivityFeaturesRegistry.xmland mapp the id to the HTML page.