Contributing¶

We very much welcome contributions to the repository! If you want to contribute bugfixes, new features (e.g., new methods for finding collective variables), or documentation (e.g., tutorials and examples), this guide is for you.

Getting started¶

Before starting to work on your changes, we suggest you open an issue (or comment on a relevant existing one) describing very briefly the changes you would like to implement. The developers might be able to give you additional guidance based on the long-term plans for the library and point you to the easiest implementation path from the start. Then

Create a fork of this repository on GitHub.
Clone your fork of the repository on your local machine.
Install the package locally (preferably in a virtual environment from the cloned source in editable mode so that your changes will be automatically installed.
```
# Activate here your Python virtual environment (e.g., with venv or conda).
cd mlcolvar
pip install -e .
```
In order to perform the regtests and build the documentation you need to install additional packages:
pip install mlcolvar[docs,test]

Once your environment is set up you are ready to implement your changes.

Overview of the GitHub workflow¶

Regardless of the type of contribution, the workflow on GitHub is the same.

Implement and test your changes (see below for guidelines specific for code, documentation, and tutorials).
When you are ready to receive feedback on your changes, navigate to your fork of mlcolvar on GitHub and open a pull request (PR). Note that after you launch the PR, all subsequent commits will be automatically added to the open PR and tested.
When you’re ready to be considered for merging, check the “Ready to go” box on the PR page to let the mlcolvar devs know that the changes are complete.
A developer will review your changes and eventually make suggestions for modifications.
Once a developer mark the PR as “approved” for merging and the continuous integration tests pass, the PR will be merged in the main codebase.

Contributing bugfixes and new features¶

If you are implementing a new CV, the documentation have guides on how to implement one from scratch or by subclassing an existing one.
Stick to the coding style guidelines when possible.
Add tests for your new code! If are contributing a bugfix, chances are our current test suite does not cover this case, adn a test should be written to avoid future regressions. If you are contributing a new feature, your tests should make sure it is working as expected.
If you are writing a new features or changing the behavior of the library, add/modify the docstrings describing the behavior of your code.

Contributing documentation¶

The main documentation of mlcolvar is inside the docs/ folder. It is written using using the reStructuredText markup syntax and automatically built in html format using Sphinx and pushed on readthedocs.io.

Classes and functions should be documented in the Python code using numpy-style docstrings. Sphinx will take care of collecting the docstrings in the code and compiling a documentation of the library’s API.

Writing short working examples of code usage in the docstring is usually tremendously helpful and very much appreciated. In numpy-style docstrings, these are written in the Examples section. Moreover, if the example is written as a Python doctest (roughly, just start each line of code in your example with >>>), this will be automatically run by the continuous integration, ensuring that the example will not go out-of-date in future code changes. To make sure your doctest run smoothly, add at the bottom of the myfile.py file including the docstring

if __name__ == '__main__':
    import doctest
    doctest.testmod()

and simply run

python myfile.py

Finally, when modifying the documentation (especially when using reStructuredText syntax), it is a very good idea to build the documentation to check the result. To do this you will need to install these additional packages:

pip install furo nbsphinx sphinx-copybutton

or more simply using:

pip install mlcolvar[doc]

Then, you can build the docs via the command

cd docs/
make html

the resulting html pages will be built in docs/_build/ and can be visualized with any browser.

Contributing tutorials¶

Tutorials are available in mlcolvar in the form of Jupyter notebooks saved in docs/notebooks/tutorials/.
As for the library’s code, stick to the coding style guidelines when possible.
Make sure the notebook runs from start to end before opening the PR as it will be automatically tested using pytest’s nbmake plugin.

Writing tests¶

mlcolvar uses pytest for automatic testing. We highly recommend installing pytest and run your tests locally before submitting the PR. You can install pytest with

pip install pytest

If you are writing tests for code in the file mlcolvar/example/folder/file.py, then your tests should be implemented as functions whose name start with test_, and they should be placed in mlcolvar/tests/test_example_folder_file.py. You can run the entire test suite with the command

pytest mlcolvar/tests/

and pytest will automatically discover all the test functions. If you want to run the tests in a single file, use

pytest mlcolvar/tests/test_my_file.py

or a single function within a file

pytest mlcolvar/tests/test_my_file.py::test_my_function

Pro tip - Consider using the @pytest.mark.parametrize decorator (see docs) to automatize testing multiple test cases and pytest.raises (see docs) to test error handling.

Coding style guidelines¶

Using coding style guidelines makes it much easier to read, understand, and search through the code. mlcolvar adheres to Python’s PEP8 convention.

If you are unfamiliar with PEP8, you might like using a linter for automatic formatting. A popular one is black. You can install it through pip

pip install black

If you want to format Jupyter notebooks, install it with the command

pip install black[jupyter]

Then run black on the file you are editing.

black your_file