| Contributor guide | |
| ================= | |
| This document lays out guidelines and advice for contributing to this project. | |
| If you're thinking of contributing, please start by reading this document and | |
| getting a feel for how contributing to this project works. If you have any | |
| questions, feel free to reach out to `Pieter Robberechts`_, the primary maintainer. | |
| .. _Pieter Robberechts: http://www.cs.kuleuven.be/cgi-bin/e-post.pl?epost=Pieter.Robberechts | |
| The guide is split into sections based on the type of contribution you're | |
| thinking of making. | |
| .. _bug-reports: | |
| Bug reports | |
| ----------- | |
| Bug reports are hugely important! Before you raise one, though, please check | |
| through the `GitHub issues`_, **both open and closed**, to confirm that the bug | |
| hasn't been reported before. | |
| When filing an issue, make sure to answer these questions: | |
| - Which Python version are you using? | |
| - Which version of socceraction are you using? | |
| - What did you do? | |
| - What did you expect to see? | |
| - What did you see instead? | |
| The best way to get your bug fixed is to provide a test case, | |
| and/or steps to reproduce the issue. | |
| .. _GitHub issues: https://github.com/ML-KULeuven/socceraction/issues | |
| Feature requests | |
| ---------------- | |
| Socceraction is not actively developed. Its primary use is to enable | |
| reproducibility of our research. If you believe there is a feature missing, | |
| feel free to raise a feature request on the `Issue Tracker`_, but please do be | |
| aware that the overwhelming likelihood is that your feature request will not | |
| be accepted. | |
| .. _Issue tracker: https://github.com/ML-KULeuven/socceraction/issues | |
| Documentation contributions | |
| --------------------------- | |
| Documentation improvements are always welcome! The documentation files live in | |
| the ``docs/`` directory of the codebase. They're written in | |
| `reStructuredText`_, and use `Sphinx`_ to generate the full suite of | |
| documentation. | |
| You do not have to set up a development environment to make small changes to | |
| the docs. Instead, you can `edit files directly on GitHub`_ and suggest changes. | |
| When contributing documentation, please do your best to follow the style of the | |
| documentation files. This means a soft-limit of 79 characters wide in your text | |
| files and a semiformal, yet friendly and approachable, prose style. | |
| When presenting Python code, use double-quoted strings (``"hello"`` instead of | |
| ``'hello'``). | |
| .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
| .. _Sphinx: http://sphinx-doc.org/index.html | |
| .. _edit files directly on GitHub: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files | |
| Code contributions | |
| ------------------ | |
| If you intend to contribute code, do not feel the need to sit on your | |
| contribution until it is perfectly polished and complete. It helps everyone | |
| involved for you to seek feedback as early as you possibly can. Submitting an | |
| early, unfinished version of your contribution for feedback can save you from | |
| putting a lot of work into a contribution that is not suitable for the | |
| project. | |
| Setting up your development environment | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| You need Python 3.9+ and the following tools: | |
| - Poetry_ | |
| - Nox_ | |
| - nox-poetry_ | |
| Install the package with development requirements: | |
| .. code:: console | |
| $ poetry install | |
| $ poetry self add poetry-plugin-export | |
| You can now run an interactive Python session. | |
| .. code:: console | |
| $ poetry run python | |
| .. _Poetry: https://python-poetry.org/ | |
| .. _Nox: https://nox.thea.codes/ | |
| .. _nox-poetry: https://nox-poetry.readthedocs.io/ | |
| Steps for submitting code | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| When contributing code, you'll want to follow this checklist: | |
| 1. Fork the repository on GitHub. | |
| 2. Run the tests to confirm they all pass on your system. If they don't, you'll | |
| need to investigate why they fail. If you're unable to diagnose this | |
| yourself, raise it as a bug report. | |
| 3. Write tests that demonstrate your bug or feature. Ensure that they fail. | |
| 4. Make your change. | |
| 5. Run the entire test suite again, confirming that all tests pass *including | |
| the ones you just added*. | |
| 6. Make sure your code follows the code style discussed below. | |
| 7. Send a GitHub Pull Request to the main repository's ``master`` branch. | |
| GitHub Pull Requests are the expected method of code collaboration on this | |
| project. | |
| Testing the project | |
| ~~~~~~~~~~~~~~~~~~~ | |
| Download the test data: | |
| .. code:: console | |
| $ poetry run python tests/datasets/download.py | |
| Run the full test suite: | |
| .. code:: console | |
| $ nox | |
| List the available Nox sessions: | |
| .. code:: console | |
| $ nox --list-sessions | |
| You can also run a specific Nox session. | |
| For example, invoke the unit test suite like this: | |
| .. code:: console | |
| $ nox --session=tests | |
| Unit tests are located in the ``tests`` directory, | |
| and are written using the pytest_ testing framework. | |
| .. _pytest: https://pytest.readthedocs.io/ | |
| Code style | |
| ~~~~~~~~~~~~ | |
| The socceraction codebase uses the `PEP 8`_ code style. In addition, we have | |
| a few guidelines: | |
| - Line-length can exceed 79 characters, to 100, when convenient. | |
| - Line-length can exceed 100 characters, when doing otherwise would be *terribly* inconvenient. | |
| - Always use double-quoted strings (e.g. ``"soccer"``), unless a double-quote occurs within the string. | |
| To ensure all code conforms to this format. You can format the code using the | |
| pre-commit hooks. | |
| .. code:: console | |
| $ nox --session=pre-commit | |
| Docstrings are to follow the `numpydoc guidelines`_. | |
| .. _PEP 8: https://pep8.org/ | |
| .. _numpydoc guidelines: https://numpydoc.readthedocs.io/en/latest/format.html | |
| Submitting changes | |
| ~~~~~~~~~~~~~~~~~~ | |
| Open a `pull request`_ to submit changes to this project. | |
| Your pull request needs to meet the following guidelines for acceptance: | |
| - The Nox test suite must pass without errors and warnings. | |
| - Include unit tests. | |
| - If your changes add functionality, update the documentation accordingly. | |
| Feel free to submit early, though. We can always iterate on this. | |
| To run linting and code formatting checks before committing your change, you | |
| can install pre-commit as a Git hook by running the following command: | |
| .. code:: console | |
| $ nox --session=pre-commit -- install | |
| It is recommended to open an issue before starting work on anything. | |
| .. _pull request: https://github.com/ML-KULeuven/socceraction/pulls | |
| .. github-only | |