Martian was originally created at 10x Genomics. We are excited to now invite the community to contribute to its development!
Contributor License Agreement
Martian is released under the MIT License. By contributing to the project, including but not limited to contributions made through issues and pull requests, you are agreeing to release any intellectual property contained in those contributions under the same terms. We cannot accept contributions which impose other licensing terms on the project.
Martian is intended to run primarily on
x86_64 Linux platforms. We target
support for running on the most recent patch versions of CentOS 5.2 or
greater and Ubuntu 10 or greater.
Martian was originally developed on 64-bit macOS, and we intend for Martian
to build on macOS, and for MRO writing tools such as
mrf to work.
We would also like
mrp to be able to run pipelines, but due to growing
differences between macOS and Linux, this could become increasingly challenging.
We would also like to see contributions from the community to enable support
The Martian Python adapter is written for Python 2.7. We have not tested with Python 3.x, but fixes are welcome.
The web user interface is built using Node 6, which is the most recent LTS version. Any fixes for newer versions are welcome, so long as they are backwards compatible.
For the open source Martian repository, only the most recent (non-
release is supported.
Development happens on the master branch, and the intent is for the master branch to always be in a "releasable" state. Features will not be back-ported to previous release branches. Pull requests for bug fixes may be cherry-picked to a previous release branches in some circumstances, but the normal action would be to create a new release off of master.
Open source Martian is a community project and is not officially supported by 10x Genomics. If you are running a 10x Genomics pipeline, please only use the released, validated version of Martian that is bundled with that pipeline.
Before submitting a bug, check to make sure it is not a duplicate of an existing issue. Also, check the documentation to ensure your environment is set up correctly. Also, verify that your repository is up to date, including submodules, in case the issue was already fixed.
For issues with
mrp, see if you can reproduce the issue
with a known-working pipeline (such as the ones in the
directory or a released 10x pipeline). If an
[id].mri.tgz was produced, include
that if possible (keeping in mind that GitHub issues are public. Make sure you
are not uploading anything you don't want the world to see!).
Local mode and cluster mode with SGE are expected to work in most configurations. Other cluster managers are less well tested, but we would love to see contributions to improve support for them.
For issues with documentation, please file them in the documentation repository.
Patch Acceptance Process
We use normal GitHub pull requests for patches. Before sending a pull request, please do the following:
- Make sure there is a bug or feature request associated with your change, and mention it in the pull request description. This allows for a separation between discussion of what should be added or fixed and how it is implemented.
- For new features, allow for a discussion on the issue so that everyone can get on board with the feature design and point out any potential pitfalls before going to the work of implementing it.
- For bug fixes, if possible create a unit test case which reproduces the bug so that we can prevent regressions.
- Make sure your change is based on the current
masterbranch HEAD revision. Patches to previous releases are accepted, but our normal process is to fix on master and cherry-pick to the release branch.
- For Go code, make sure it is run through
go vet. For python code, use
pylintbefore submitting. These tools prevent distracting churn in formatting and provide a first line of defense against error-prone code.
- Ideally, write a unit test or integration test to cover your new code. Test coverage is very light right now, but we would like to improve it. Test-only pull requests are very welcome!
- Make sure your change builds and passes the basic integration tests. Run
make && make longtests.
- Wait for a reviewer to be assigned to the pull request. Please be patient as the development team has many priorities to balance.
- Complete the review process. This may require some back and forth with the reviewer. Depending on how long this takes, it may be necessary to periodically merge changes from master into the pull request branch.
Martian is under active development internally, so many things you might want are already planned! See the roadmap for our current plans. That said, we have limited resources, and your favorite feature request might not be something we can prioritize. Pull requests are especially welcome for the following:
- Cluster mode improvements, particularly on non-SGE clusters. We have an
SGE cluster, but we do not yet have a Slurm or LSF cluster to test on. Those
cluster managers are increasing in popularity, so we'd love to see improvements
to support for them, or other cluster managers which we haven't heard of. In
particular, additions or improvements to the
jobmanagers/config.jsonand template examples, or implementation of queue-querying scripts like
sge_queue.pyfor other cluster types.
- Support for more stage code languages. For compiled languages other than Go, it's best to keep those in a separate repository as we did for Rust, since they cannot and should not be tightly coupled to a specific version of Martian. For scripting languages such as Python, however, a front-end wrapper adapter may simplify stage code development. Be sure to include additions to the mro lexer and grammar to support the new mode. Be sure to read the API documentation before implementing an adapter.
- Improvements for Python 3 compatibility are welcome. We've done no testing at all with Python 3.
- Editor support for mro. Currently we have editor plugins for Vim, Atom, and Sublime editors.