Developer/Contributor Guidelines

Note

Parts of this document are based on the xarray contributing guide which itself is heavily based on the Pandas Contributing Guide.

Bug Reports and Feature Requests

Bug reports are an important part of making TCTrack more stable. Having a complete bug report allows others to reproduce the bug and provides insight into fixing.

Trying out the bug-producing code on the main branch is often a worthwhile exercise to confirm that the bug still exists. It is also worth searching existing bug reports and pull requests to see if the issue has already been reported and/or fixed.

Submitting a bug report

If you find a bug in the code or documentation, submit a ticket to the Issue Tracker.

When reporting a bug, please include the following:

  1. A short, self-contained Python snippet reproducing the problem. You can format the code nicely by using GitHub Flavored Markdown:

    ```python
import tctrack

"""Your code here."""
...
```

  2. Explain why the current behavior is wrong/not desired and what you expect instead.

The issue will then show up to the TCTrack community and be open to comments/ideas from others.

See this stackoverflow article for more detailed tips on writing a good bug report.

If you have fixed the issue yourself in your own version of TCTrack please note this on the issue and follow up by opening a pull request.

Submitting a feature request

If there is a feature you think would be useful to add to TCTrack please make a request using the Issue Tracker. When doing so please try to include the following details:

  1. A clear description of the functionality you would like to see added and why you feel it would be useful.

  2. Any external references that are helpful/required to understand and implement your request in detail.

  3. A short code snippet indicating what the desired API might look like.

If you have already implemented the feature yourself in your own version of TCTrack please note this on the issue and follow up by opening a pull request.

Pull Requests

If you have something to contribute to the TCTrack codebase this is done by opening a pull request to the main repository on GitHub.

Here is a summary of the expected workflow when contributing:

  1. Make sure there is an open issue on the Issue Tracker as described above detailing the bug/feature that you are addressing.

  2. Fork the main repository into your own personal GitHub space, and then clone and work on this fork. You should work on a branch within this fork with a sensible name that reflects what you are working on.

  3. As you work on the code, commit your changes in sensible-sized chunks with clear commit messages. A commit should detail any changes made to perform a particular action en route to the overall goal. When writing commit messages remember that it needs to be clearly understandable to other developers as to what they contribute. See previous commits in the project for examples.

    As you work keep the following aspects in mind:

    1. Do not place large changes to multiple files in a single commit.

    2. Try and remember to apply the stylistic checks and balances to your code before committing.

    3. Make sure that you include appropriate tests alongside your code contributions. Code without tests will not be merged.

    4. Make sure that you include/update any docstrings in the code, and that they conform to the numpy style. See the rest of the code for examples.

    5. Make sure that you update the documentation where necessary to reflect the additions you have made. If adding a significant top-level feature to the code you may want to update the relevant pages to showcase your additions.

  4. Once you push code back to your GitHub fork you can open a pull request. For small bug-fixes and features you may wait until you feel things are complete before opening the pull request. However, if you wish for feedback/intermediate review then please open the pull request in draft mode during development.

  5. When opening a pull request ensure that it contains:

    • A sensible title summarising its contribution.

    • A reference to the issue number(s) that it is addressing.

    • A description of what has been done making it easy for the maintainers to review.

Once a pull request is opened it will be reviewed by the project maintainers and any requests for changes/improvement fed back to the author. Once the maintainers are happy, your code will be approved and the pull request merged!

Code quality and formatting

Writing good code is not just about what you write. It is also about how you write it. During continuous integration several tools will be run to check your code for stylistic errors. Generating any warnings will cause these tests to fail. Thus, good style is a requirement for submitting code to TCTrack.

TCTrack uses tools to ensure consistent and quality code formatting throughout:

  • ruff for:

    • standardized code formatting

    • code quality checks

    • checking docstrings against the numpy conventions

  • mypy for static type checking of type hints.

These will be checked on all pull requests and commits to main, so it is suggested you run them on your code before committing.

This can be done with a development install by running the following bash commands from the root directory:

ruff format src/
ruff check src/
mypy src/
blackdoc docs/

Sometimes it makes sense to disable a ruff warning. We generally prefer that this is done on a case-by-case basis in the code. If you have justification for turning off any warnings in your contribution please document them in your pull request.

The full ruff configuration for the project is contained in the pyproject.toml file.

Code quality is enforced for pull requests through a code-quality continuous integration workflow run using GitHub actions.

Testing

All code contributions should have accompanying unit and integration tests to ensure that all parts of the code are functioning properly.

TCTrack uses the pytest framework for testing, with subprocess calls mocked with pytest-mock in unit tests.

Tests are stored separately from the main code in the tests/ directory at the root of the package. There are separate subdirectories for unit (testing the TCTrack Python code) and integration (testing the interaction with other libraries) tests.

To run the tests from a development install use, from the command-line:

pytest tests/unit
pytest tests/integration

to run both the unit and integration tests sequentially. Note that the integration tests require installation of third-party libraries that TCTrack wraps.

Code quality of the tests is maintained using ruff and mypy (see Code quality and formatting). Check these from a development install by running:

ruff format tests/
ruff check tests/
mypy src tests

Note that mypy is run over both src and tests to pick up the TCTrack type hints.

Testing standards are enforced for pull requests through continuous integration workflows run using GitHub actions. These are run for a number of Python versions and operating systems.

Documentation

The documentation is written in reStructuredText and built using Sphinx. The Sphinx Documentation has an excellent introduction to reST in addition to other aspects of Sphinx.

Sphinx allows much of the API documentation to be be generated automatically from the docstrings in the source code. This is why it is important to put time into these.

The rest of the documentation, such as the installation and getting started pages, and the contribution guidelines that you are reading right now, are written out and stored in the docs/ directory of the code.

To build the documentation on a development install run:

cd docs/
make clean
make html

This will generate HTML output files in the folder docs/_build/html/ that can be viewed in a browser.