Skip to content

Latest commit

 

History

History
313 lines (221 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

313 lines (221 loc) · 11.6 KB
Raw

Contributing to pymovements

Thank you for taking your time to contribute to pymovements!

We encourage you to report any bugs or contribute to new features, optimisations or documentation.

Here we give you an overview of the workflow and best practices for contributing to pymovements.

Questions: If you have any developer-related questions, please open an issue or write us at pymovements-list@uni-potsdam.de

Table of Contents

Code of Conduct

Everyone participating in the pymovements project, and in particular in our issue tracker and pull requests, is expected to treat other people with respect and more generally to follow the guidelines articulated in the Python Community Code of Conduct.

Reporting Bugs

If you discover a bug, as a first step please check the existing Issues to see if this bug has already been reported.

In case the bug has not been reported yet, please do the following:

  • Open an issue.
  • Add a descriptive title to the issue and write a short summary of the problem.
  • We provide you with a default template to guide you through a typical reporting process.
  • Adding more context, including error messages and references to the problematic parts of the code, would be very helpful to us.

Once a bug is reported, our development team will try to address the issue as quickly as possible.

First-time Contributors

If you're looking for things to help with, try browsing our issue tracker first. In particular, look for:

You do not need to ask for permission to work on any of these issues. The current status of the issue will let you know if someone else is or was already working on it.

To get help fixing a specific issue, it's often best to comment on the issue itself. You're much more likely to get targeted help if you provide details about what you've tried and where you've looked.

To start out with developing, install the dependencies and create a branch for your contribution.

Create a pull request when you feel confident to publish your progress. Don't hesitate if it's a work in progress, we can give you early feedback on your work. If you can, try to add unit tests early on to verify correctness.

Getting Started

This is a general guide to contributing changes to pymovements.

Before you start developing, make sure to read our documentation first.

Development Installation

Make sure to install the latest pymovements version from the main branch.

git clone https://github.com/aeye-lab/pymovements.git
cd pymovements
pip install -e .

If you have a problem e.g. command not found: pip, check whether you have activated a virtual environment.

Creating a Branch

Before you start making changes to the code, create a local branch from the latest version of the main branch.

git checkout main
git pull origin main
git checkout -b feature/your-feature-branch

To shorten this call you can create a git alias via

git config alias.newb '!f() { git checkout main; git pull; git checkout -b $1; }; f'

You can then update main and create new branches with this command:

git newb your-new-branch

We do not allow for pushing directly to the main branch and merge changes exclusively by pull requests.

We will squash your commits into a single commit on merge to maintain a clean git history. We use a linear git-history, where each commit contains a full feature/bug fix, such that each commit represents an executable version. This way you also don't have to worry much about your intermediate commits and can focus on getting your work done first.

Code Style

We write our code to follow PEP-8 with a maximum line-width of 100 characters. We additionally use type annotations as in PEP-484. For docstrings we use the numpydoc formatting standard.

We use flake8 for quick style checks and pylint for thorough style checks and mypy for checking type annotations.

You can check your code style by using pre-commit. You can install pre-commit via pip:

pip install pre-commit
pip install pylint

To always run style checks when pushing commits upstream you can register a pre-push hook by

pre-commit install --hook-type pre-push

If you want to run pre-commit for all your currently staged files simply use

pre-commit

You can find the names of all defined hooks in the file .pre-commit-config.yaml.

If you want to run a specific hook you can use

pre-commit run mypy
pre-commit run pydocstyle

If you want to run a specific hook on a single file you can use

pre-commit run mypy --files src/pymovements/gaze/transforms.py

If you want to run all hooks on all git repository files use

pre-commit run -a

For running a specific hook on all git repository files use

pre-commit run mypy -a

Testing

Tests are written using Pytest and executed in a separate environment using Tox.

If you have not yet installed tox you can do so via

pip install tox

You can run all tests on all supported python versions run by simply calling tox in the repository root.

tox

Running tox the first time in the repository will take a few minutes, as all necessary python environments will have to be set up with their dependencies. Runtime should be short on the subsequent runs.

If you add a new feature, please also include appropriate tests to verify its intended functionality. We try to keep our code coverage close to 100%.

It is possible to limit the scope of testing to specific environments and files. For example, to only test event related functionality using the Python 3.9 environment use:

tox -e py39 -- tests/unit/events

Documentation

Make sure to add docstrings to every class, method and function that you add to the codebase. Docstrings should include a description of all parameters, returns and exceptions. Use the existing documentation as an example.

The API-documentation is generated from the numpydoc-style docstring of the respective modules/classes/functions by Sphinx. You can build the documentation locally using the respective tox environment:

tox -e docs

It will appear in the build/docs directory. Please note that in order to reproduce the documentation locally, you may need to install pandoc. If necessary, please refer to the installation guide for detailed instructions.

To rebuild the full documentation use

tox -e docs -- -aE

Pull Requests

Once you are ready to publish your changes:

  • Create a pull request (PR).
  • Provide a summary of the changes you are introducing according to the default template.
  • In case you are resolving an issue, don't forget to add a reference in the description.

The default template is meant as a helper and should guide you through the process of creating a pull request. It's also totally fine to submit work in progress, in which case you'll likely be asked to make some further changes.

If your change will be a significant amount of work to write, we highly recommend starting by opening an issue laying out what you want to do. That lets a conversation happen early in case other contributors disagree with what you'd like to do or have ideas that will help you do it.

The best pull requests are focused, clearly describe what they're for and why they're correct, and contain tests for whatever changes they make to the code's behavior. As a bonus these are easiest for someone to review, which helps your pull request get merged quickly. Standard advice about good pull requests for open-source projects applies.

Do not squash your commits after you have submitted a pull request, as this erases context during review. We will squash commits when the pull request is ready to be merged.

Continuous Integration

Tests, code style and documentation are all additionally checked using a GitHub Actions workflow which executes the appropriate tox environments. Merging of Pull requests will not be possible until all checks pass.

Core Developer Guidelines

Core developers should follow these rules when processing pull requests:

  • Always wait for tests to pass before merging PRs.
  • Use "Squash and merge" to merge PRs.
  • Delete branches for merged PRs.
  • Edit the final commit message before merging to conform to the Conventional Commit specification:
<type>[optional scope]: <description> (#PR-id)

- detailed description, wrapped at 72 characters
- bullet points or sentences are okay
- all changes should be documented and explained
- valid scopes are the names of the top-level directories in the package, like `dataset`, `gaze`, or `events`

Make sure:

  • that when merging a multi-commit PR the commit message doesn't contain the local history from the committer and the review history from the PR. Edit the message to only describe the end state of the PR.
  • that the maximum subject line length is under 50 characters
  • that the maximum line length of the commit message is under 72 characters
  • to capitalize the subject and each paragraph.
  • that the subject of the commit message has no trailing dot.
  • to use the imperative mood in the subject line (e.g. "Fix typo in README").
  • if the PR fixes an issue, that something like "Fixes #xxx." occurs in the body of the message (not in the subject).
  • to use Markdown for formatting.

License

Please note that by contributing to the project you agree that it will be licensed under the License of this project.

If you did not write the code yourself, ensure the existing license is compatible and include the license information in the contributed files, or obtain permission from the original author to relicense the contributed code.

Questions

If you have any developer-related questions, please open an issue or write us at pymovements-list@uni-potsdam.de