Contributing

This is primarily an academic project, and everyone is welcome to contribute. The project is hosted on http://github.com/SimTk/msmbuilder

Submitting a bug report

If you experience issues using this package, do not hesitate to submit an issue to the bug tracker. You’re also invited to post feature requests or links to pull requests.

Retrieving the latest code

We use Git for version control and GitHub for hosting our main repository.

You can check out the latest sources with the command:

git clone git://github.com/SimTk/msmbuilder.git

or if you have write privileges:

git clone git@github.com:SimTk/msmbuilder.git

If you run the development version, it is cumbersome to reinstall the package each time you update the sources. It is thus preferred that you add the msmbuilder directory to your PYTHONPATH and build the extension in place:

python setup.py build_ext --inplace

Contributing code

Note

To avoid duplicating work, it is highly advised that you contact the developers on the issue tracker before starting work on a non-trivial feature.

How to contribute

The preferred way to contribute to msmbuilder is to fork the main repository on GitHub:

  1. Create an account on GitHub if you do not already have one.

  2. Fork the project repository: click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub server.

  3. Clone this copy to your local disk:

    $ git clone git@github.com:YourLogin/msmbuilder.git

  4. Create a branch to hold your changes:

    $ git checkout -b my-feature

    and start making changes. Never work in the master branch!

  5. Work on this copy, on your computer, using Git to do the version control. When you’re done editing, do:

    $ git add modified_files
$ git commit

    to record your changes in Git, then push them to GitHub with:

    $ git push -u origin my-feature

Finally, go to the web page of your fork of the msmbuilder repo, and click ‘Pull request’ to send your changes to the maintainers for review. request. This will send an email to the maintainers.

(If any of the above seems like magic to you, then look up the Git documentation on the web.)

It is recommended to check that your contribution complies with the following rules before submitting a pull request:

  • Follow the coding-guidelines (see below).

  • All public methods should have informative docstrings with sample usage presented as doctests when appropriate.

  • All other tests pass when everything is rebuilt from scratch. On Unix-like systems, check with:

    $ nosetests

You can also check for common programming errors with the following tools:

  • No pyflakes warnings, check with:

    $ pip install pyflakes
$ pyflakes path/to/module.py

  • No PEP8 warnings, check with:

    $ pip install pep8
$ pep8 path/to/module.py

  • AutoPEP8 can help you fix some of the easy redundant errors:

    $ pip install autopep8
$ autopep8 path/to/pep8.py

Note

The current state of the msmbuilder code base is not compliant with all of those guidelines, but we expect that enforcing those constraints on all new contributions will get the overall code base quality in the right direction.

Note

For two very well documented and more detailed guides on development workflow, please pay a visit to the Scipy Development Workflow and the Astropy Workflow for Developers pages.

Coding guidelines

The following are some guidelines on how new code should be written. Of course, there are special cases and there will be exceptions to these rules. However, following these rules when submitting new code makes the review easier so new code can be integrated in less time.

Uniformly formatted code makes it easier to share code ownership. The msmbuilder project tries to closely follow the official Python guidelines detailed in PEP8 that detail how code should be formatted and indented. Please read it and follow it.

In addition, we add the following guidelines:

  • Use underscores to separate words in non class names: n_samples rather than nsamples.
  • Avoid multiple statements on one line. Prefer a line return after a control flow statement (if/for).
  • Please don’t use `import *` in any case. It is considered harmful by the official Python recommendations. It makes the code harder to read as the origin of symbols is no longer explicitly referenced, but most important, it prevents using a static analysis tool like pyflakes to automatically find bugs.
  • Use the numpy docstring standard in all your docstrings.

A good example of code that we like can be found here.

Building the docs

To build the documentation on your local machine, you need to first ensure that the numpydoc package is installed. The documentation itself can be built with a make command from within the docs/sphinx directory:

$ easy_install numpydoc
$ make html
Versions