Contributors’ guide

We gladly welcome contributions in the form of pull requests at https://github.com/temfpy/temfpy/pulls.

Best practices

Discuss before you contribute

Before contributing a PR, please open an issue to discuss your suggested changes. This ensures that your contribution will fit with the overall plans for the library and that no one else starts working on the same thing at the same time.

No giant PRs

If possible, pull requests should be small, ideally changing one single thing. You should only deviate from this if one change would break something else, or if the same change would make sense in several different contexts.

Likewise, each commit should be a single, self-contained change, described in a clear commit message.

Document your changes

In order to be accessible for non-expert users, it is critical to maintain a good standard of documentation, both on this site and in the docstrings.

Therefore, we require that every new function, method, or class carry a docstring in Napoleon’s “NumPy” format that explains in reasonable detail what they do. Functions should also come with type hints indicating their input and output types.

If your additions are meant to be accessible to end users, you should also ensure that they appear in the autogenerated reference documentation:

  • If they are in existing modules, you should expand the corresponding file in directory docs/source/reference.

  • If you started a new module, you should add a similarly structured file to describe it, and add it to the list in docs/source/index.md to make sure that it appears in the table of contents.

Coding style

Code must follow PEP 8. For consistency, we also use the code formatter black and the linter ruff. These will be installed automatically if you select the [dev] option when installing TeMFpy.

If you have installed pre-commit, they will be run automatically before you commit or if you run the command below.

pip install pre-commit
pre-commit run --all

How to submit a PR

Please follow these steps to contribute a PR:

  1. Fork the TeMFpy repository by clicking the Fork button on the repository page. This creates a copy of the repository for you to work in.

  2. pip install your fork from source with the development dependencies. This allows you to modify the code and immediately test it out:

    git clone https://github.com/YOUR_USERNAME/temfpy
cd temfpy
pip install -e '.[dev]'  # Installs TeMFpy from the current directory with development dependencies
pre-commit install # Install the pre-commit hook that checks your commit for good formatting

  3. Create a separate branch for your changes:

    git checkout -b name-of-change

  4. Implement your contribution and Document your changes.

  5. Run black and ruff to enforce a consistent coding style:

    pre-commit run --all-files

    and fix any errors highlighted but not fixed by ruff.

  6. Commit your changes:

    git add file1.py file2.py ...
git commit -m "Your commit message"

    and upload them to your fork:

    git push --set-upstream origin name-of-change

  7. Create a pull request on the TeMFpy repository. We will review it and might suggest changes to the code before adding it to the upstream library.

Acknowledgement

This guide is based on Contributing to NetKet.