Firstly, thank you for taking an interesting in contributing! Mercator is an open-source project, and welcomes contributions in the form of feature code, bug reports & fixes, tests, feature suggestions and anything else which may help to make it better software.
Mercator is developed using Fury, which may be installed by running the launcher script in the root directory, like so:
./fury system install
If you do not wish to install Fury, the same script may be used to run Fury without modifying any of your system settings.
The simplest way to compile Mercator is to run,
fury
however, useful variations include,
fury -w: watch for source-file changes, and recompile as necessaryfury build console -I: compile and launch the Scala REPL, ignoring any compile errorsfury -F -f <dir>: compile and save a fat JAR filefury test: compile and run the test suite
Fury is not yet stable, so please report any issues relating to Fury.
We recommend using Visual Studio Code with the Scala Metals extension for developing.
It’s a good idea to discuss potential changes with one of the maintainers before starting work. Although efforts are made to document future development work using the issue tracker, it will not always be up-to-date, and the maintainers may have useful information to share. The worst-case scenario would be for a contributor to spend a large amount of time producing a PR, only for it to be rejected by the maintainers for not fitting with their ideas. A quick conversation before starting work can save a lot of time.
If a response is not forthcoming in the Riot chatroom, contacting one of the project maintainers directly but publicly may help. Please do not contact the maintainers privately, as it misses a good opportunity to share knowledge with a wide audience. Jon Pretty can usually be contacted on Twitter.
All development work—whether bugfixing or implementing new features—should have a corresponding
issue before work starts. If you have commit rights to the propensive/mercator repository, please only push to
branches which named after the issue number, prefixed with issue/, for example, issue/423.
Pull requests should try to follow the coding style of existing code in the repository. They are unlikely to be rejected on grounds of formatting, except in extreme cases. Mercator does not use automatic code-formatting because it has proven to produce unreliable results (and furthermore, hand-formatting is not particularly laborious).
Unfortunately an official style guide does not yet exist.
Pull requests should have at least one review before being merged. When opening a PR, contributors are welcome to suggest a reviewer. Pull requests should be left in draft mode until they are believed to be ready for review.
For code contributions, we prefer pull requests with corresponding tests. But we should not let perfect be the enemy of the good. Changes which break existing tests, however, are likely to be rejected during review.
New issues are welcome, both as bug reports and feature suggestions. It is generally true that more detail is preferable, and the clearest and most detailed reports will most likely be addressed sooner, but a short report from a busy developer is still preferred over a bug we never hear about. We will ask for more detail in triage if it’s needed.
Contributors and other participants in online discussions are expected to be polite and to nurture a pleasant development environment for all Mercator’s users. Propensive OÜ reserves the right to censure and—in extreme cases—ban users whose behavior, in their opinion, is detrimental toward this goal.