Skip to content

Latest commit

 

History

History
205 lines (134 loc) · 6.16 KB

CONTRIBUTING.rst

File metadata and controls

205 lines (134 loc) · 6.16 KB
Raw

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.

The guide is split into sections based on the type of contribution you're thinking of making.

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.

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.

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').

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:

Install the package with development requirements:

$ poetry install
$ poetry self add poetry-plugin-export

You can now run an interactive Python session.

$ poetry run python

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:

$ poetry run python tests/datasets/download.py

Run the full test suite:

$ nox

List the available Nox sessions:

$ nox --list-sessions

You can also run a specific Nox session. For example, invoke the unit test suite like this:

$ nox --session=tests

Unit tests are located in the tests directory, and are written using the pytest testing framework.

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.

$ nox --session=pre-commit

Docstrings are to follow the numpydoc guidelines.

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:

$ nox --session=pre-commit -- install

It is recommended to open an issue before starting work on anything.