Contributing to JetBrains MPS Project
File a Bug Report
Bug reports are the simplest way you can get involved. Bug reports take little time to file and are very helpful to developers. When you discover a problem, please report it. Make sure you provide information about your environment (OS, JDK and MPS version), steps to reproduce the issue, as well as a textual description of the problem. You can file a bug in the JetBrains MPS YouTrack bug database. Before submitting an issue, you may also want to search for already submitted ones describing the same problem - and if you find one, feel free to vote for it.
Create Unit Test reproducing the problem
Bug reports are helpful, but as you probably know, most of the problems can be reproduced/checked by automated JUnit tests. It's much more easy and convenient for our developers to reproduce the problem by running a test case instead of manually going through a list of steps to reproduce the bug. If you invest a little bit more time and create a JUnit test reproducing your problem, we will usually be able to fix/process your bug faster.
Contribute code indirectly
If you are not an MPS contributor, you can contribute your code in two ways:
A pull request to the MPS github repository (preferred)
A git patch file
In either case branch-off your code from the master branch or from a specific release branch (e.g. 2028.3).
In ideal case attach the patch or a link to your pull request to the corresponding request in the JetBrains MPS YouTrack bug database. You can either file a new issue with the patch attached, or attach a patch to an issue submitted by another user. A developer will review your patch/pull request and, if it meets the quality criteria and fits with the rest of the code, you'll be notified about the acceptance of the patch. As it was already mentioned, patches having a unit-test attaches should be processed faster.
Contribute code directly
Become a contributor and contribute directly into the git repository. This will require some up-front ceremony to grant you the necessary permissions, but regular contributions then become easier.
How to work with the MPS sources
Although the main Git repository is located at JetBrains (see the Accessing MPS Git Repository section below), we keep a public mirror at GitHub. The mirror is primarily meant to be an easy-to-use repository for external contributors. Here's a cookbook on how to contribute your idea to MPS through GitHub
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
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 project structure
Admittedly the overall project structure is very difficult to see from the hierarchy of modules and packages in IDEA and MPS and you'll be having hard time understanding how the pieces fit together. We've collected a few guidelines to help you in many cases. For the rest, please get in touch with us directly or through the forum.
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.
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.
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 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