Contributing

Thanks for considering contributing to tigrqc! We welcome contributions of any kind.

Style

As much as possible please try to adhere to PEP8 conventions and try to include type hints. We use these tools to enforce these things:

• flake8
• isort
• mypy
• pylint

Commit Conventions

We try to tag our commits with semantic tags (some of our tooling uses these tags).

Please prefix each of your commits with one of these tags:

• [BUILD]: For build-related changes
• [CHORE]: For small changes that don't really fit anywhere else
• [CI]: For continuous integration related changes
• [DEP]: For dependency changes
• [DOC]: For documentation additions or changes
• [ENH]: For commits that add new functionality or features or performance improvements
• [FIX]: For bug fixes
• [REF]: For refactoring
• [STY]: For PEP or other style-related changes.
• [TEST]: For changes that add or update tests

Reporting Bugs

Please try to include these details when making a bug report:

• Python version
• OS type and version
• Which version or specific commit of tigrqc you're running
• A description of the bug (what you expected to happen and what actually happened)
• The specific set of steps to reproduce the bug you've found

Documentation Changes

We use mkdocs to generate our documentation. This means that our documentation configuration is stored in 'mkdocs.yml'. We use mkdocs-material as our theme.

We use our repo's README.md as our 'index.md' / Home page and our API reference documentation is autogenerated at build time by the script in the 'docs' folder. Any markdown files dropped into the 'docs' folder will be automatically included as well.

You can install the extra packages required to build the documentation with:

# If using pip
pip install -e .[docs]

# If using uv
uv sync --group docs

While editing the documentation you can check your results locally with:

# Run from the project's root dir
mkdocs serve

Dependency Changes

We use uv to manage our project's dependencies, because it's better at creating repoducible installations than pip and comes with the added benefit of still letting users use pip if they prefer!

If you have to add / change any dependencies please use uv to do it and commit the changes it makes to pyproject.toml and uv.lock!

Some useful commands to know for this:

# Creating the initial env
uv sync
# Creating one with optional packages installed in the env
uv sync --group GROUPNAME
# Install all optional dependencies
uv sync --all-groups


# Add a new dependency
uv add <packagename>
# Add a new dependency to an optional group
uv add --group GROUPNAME <packagename>


# Update a dependency's version
uv update [<packagename>]

Running Tests

We use pytest for our tests. To run tests locally, first install the extra dependencies:

# If using uv
uv sync --group tests

# If using pip
pip install .[tests]

Then from the root folder of the project:

pytest tests