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.