Contributing

MSMBuilder is a collaborative project and we welcome all contributions.

Users

If you find a bug or have a question, consider opening an issue. We’re mainly grad student researchers, not software developers or support staff, so have patience if someone doesn’t respond immediately. Don’t be afraid to “bump” a thread if it’s been a couple days.

If you are an MSMBuilder user, we encourage you to “watch” the issue tracker. The developers will often solicit feedback about design decisions and features. Your input is important! You can also contribute by answering other users’ questions.

Developers

To contribute a bug-fix or improvement, submit a pull request. Make sure the changed code is pep8 compliant. Add a simple test case that would have failed but now passes with your contribution. Make a note of the change in the changelog by editing docs/changelog.rst. If you need help or clarification on any of these points, open a pull request and we’ll be more than happy to help.

To contribute a new feature, submit a pull request. The code should be pep8 compliant. Include a suite of tests to (1) verify your feature is working as intended and (2) will not be broken in the future. Describe the feature in the changelog by editing docs/changelog.rst. Provide literature citations if applicable. We encourage you to add an example IPython notebook that demonstrates your new feature. It should run quickly and make a pretty plot. This is a great way to advertise your new feature. If you need help or clarification on any of these points, open a pull request and we’ll be more than happy to help.

Tests

We use unit testing to make sure things work properly to start with, and don’t get broken in the future. Tests are organized into files roughly corresponding to msmbuilder modules in msmbuilder/tests/test_*.py. Each test script contains a number of short, self-contained functions beginning with the name test_. You can add new tests to an existing file, or create a new file if it’s appropriate. The new tests will automatically get discovered and run by our continuous integration (CI) workers. Don’t use relative imports in the tests. Don’t use docstrings in the tests. nose (our test runner) will use the docstrings as the name of the test, and this is often not what we want. Include pseudo-docstrings as ordinary comments at the top of each function and name the test function descriptively

To run the tests, install msmbuilder (python setup.py install or python setup.py develop) and then run nosetests msmbuilder outside of the source directory. It won’t import the right thing if you run from the source directory.

Examples

Contribute an example IPython notebook by putting it in the examples/ directory. We’ll probably format it and do the incantations to make it show up in the published docs. Clear all outputs before committing the notebook in git.

To include an example notebook in the docs (contributors other than core-developers ignore this): Create docs/examples/Notebook-Name.rst:

Notebook Pretty Title
=====================

.. notebook:: Notebook-Name

And add Notebook-Name to the toctree in docs/examples/index.rst. The rendering code is in docs/sphinxext/notebook_sphinxext.py. Presumably, we could streamline this process so you only have to deposit a notebook in examples/ and it will automatically get added to the docs.