MPS 2022.3 Help

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.

Contributions

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 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.

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 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.

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:

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.

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.

Structure

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

The structure tool window

  • 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.

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.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.

Last modified: 14 September 2022