Contributor Guide

Thank you for your interest in improving this project. This project is open-source under the GPL-3 license and welcomes contributions in the form of bug reports, feature requests, and pull requests.

Here is a list of important resources for contributors:

Issues🔗

Issue Tracker can be used for suggestions for improvements, bug reports and questions.

How to report a bug🔗

Report bugs on the Issue Tracker.

When filing an issue, make sure to answer these questions:

Which operating system and Python version are you using?
Which version of this project 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.

How to set up your development environment🔗

You need Python 3.9+, poetry and Nox.

How to test the project🔗

Run the full test suite:

nox -s tests

Run the tests for only one version of Python:

nox -s tests -p 3.13

Run the tests for just one between renardo and foxdot:

nox -t renardo
nox -t foxdot

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

How to document changes🔗

mkdocs-material is being used to create project documentation along with mkdocstrings to document the API in numpydoc format.

The project documentation is located in the docs/ directory. At first, if you need to change it, this can only be done in docs/en/ in English.

The API documentation is done in docstring in the numpydoc standard.

You can upload a documentation server locally to see changes in real time before committing them. Use the command below to start the server:

nox -s docs

Translations🔗

Contributions to translations are always welcome.

The mkdocs plugin mkdocs-static-i18n is used to create the translation framework. The internationalization settings are located in the mkdocs.yml file in the plugins section. A point of attention is languages, if you are adding a new language, start there:

Example:

plugins:
  - i18n:
      # ...
      languages:
        - locale: en
          default: true
          name: English
        - locale: es
          name: Español

You can also translate the site description and its navigation bar.

plugins:
  - i18n:
      # ...
      languages:
        - locale: en
          default: true
          name: English
        - locale: es
          name: Español
          nav_translations:
            "Contributor Guide": Guía para Contribuyentes

After that, create a directory with the same name as the locale in question within docs/.

mkdir docs/es

The file structure of this directory must follow the same as the others (at least the section that is to be translated, if it does not exist, the standard section in English will be used).

docs
├── assets
│  ...
├── en
│  ├── api
│  │  ├── chord.md
│  │  └── pchord.md
│  ├── changelog.md
│  ├── contributing.md
│  ├── index.md
│  └── tutorial
│     ├── theory.md
│     └── usage.md
└── es
   ├── contributing.md
   ├── index.md
   └── tutorial
      ├── theory.md
      └── usage.md

This way internationalization can be done.

How to submit changes🔗

Open a pull request to submit changes to this project.

Your pull request needs to meet the following guidelines for acceptance:

The CI must pass without errors and warnings.
Include unit tests. This project maintains code coverage.
If your changes add functionality, update the documentation accordingly.

Feel free to submit early, though — we can always iterate on this.