Contribution Guidelines

To contribute to pysagas, please carefully read the instructions below.

Seek Feedback Early

Please open an issue before a pull request to discuss any changes you wish to make.

Setting up for Development

  1. Create a new Python virtual environment to isolate the package and its dependencies. You can do so using Python’s venv or anaconda.

  2. Install the code in editable mode using the command below (run from inside the pysagas root directory). Also install all dependencies using the [all] command, which includes the developer dependencies.

pip install -e .[all]

  1. Install the pre-commit hooks. This will check that your changes are formatted correctly before you make any commits.

pre-commit install

  1. Start developing! After following the steps above, you are ready to start developing the code. Make sure to follow the guidelines below.

Developing PySAGAS

  • Before making any changes, fork this repository and clone it to your machine.

  • Run black on any code you modify. This formats it according to PEP8 standards.

  • Document as you go: use numpy style docstrings, and add to the docs where relevant.

  • Write unit tests for the code you add, and include them in tests/. This project uses pytest.

  • Commit code regularly to avoid large commits with many unrelated changes.

  • Write meaningful commit messages, following the Conventional Commits standard. This is used for the purpose of maintaining semantic versioning and automated changelogs. The Python package commitizen is a great tool to help with this, and is already configured for this repo. Simply stage changed code, then use the cz c command to make a commit. If you do not wish to do this, your commits will be squashed before being merged into main.

  • Open a Pull Request when your changes are complete and ready to be merged.

Building the Docs

PySAGAS is documented using Sphinx. To build the documentation, run the commands below from the root directory.

cd docs/
make html
xdg-open build/html/index.html

If you are actively developing the docs, consider using sphinx-autobuild. This will continuosly update the docs for you to see any changes live, rather than re-building repeatadly. From the root directory, run the following command:

sphinx-autobuild docs/source/ docs/build/html --open-browser --watch pysagas/