Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (137 loc) · 5.6 KB

CONTRIBUTING.md

File metadata and controls

188 lines (137 loc) · 5.6 KB
Raw
Created 2026-07-08
Last-Modified 2026-11-05
SPDX-FileCopyrightText 2026-present Arthit Suriyawongkul
SPDX-FileType DOCUMENTATION
SPDX-License-Identifier CC0-1.0

Contributing to Pitloom

Thanks for your interest in contributing to Pitloom!

Ways to contribute

There are many ways to contribute, both with and without writing code:

  • Promote the project: Mention Pitloom in articles, link to it from your site, or star the repository to boost visibility.
  • Triage issues: Reproduce reported bugs, answer questions, and add context to open issues.
  • Review pull requests: Provide feedback on code and documentation submitted by other contributors.
  • Report feedback: Open detailed bug reports or feature requests, and upvote existing issues that affect you.
  • Improve documentation: Fix typos, write tutorials, or add usage examples.
  • Contribute code: Fix bugs, write tests, or implement new features.

Workflow and guidelines

Reporting issues and proposing features

We use GitHub issues to track all bugs and feature requests.

  • Search existing GitHub Issues before opening a new one.
  • Open an issue to discuss proposed changes before starting significant work.

Pull requests and commits

  • Fork the repository and create your branch off main.

  • Keep changes focused and scoped to a single concern.

  • Write descriptive commit messages explaining user impact, not just implementation details (see How to Write a Git Commit Message).

  • All commits must be signed off to certify compliance with the Developer Certificate of Origin (DCO):

    git commit -s

  • Update CHANGELOG.md for user-visible changes, following Keep a Changelog: one short entry per change (the PR holds the detail), entries in each section sorted by PR number. Older releases are in CHANGELOG-archive.md.

AI policy

Do not submit issues or pull requests generated by fully automated AI tools. Every AI-assisted contribution must be personally reviewed, tested, and understood, and you must be able to explain all changes upon request.

Do not paste raw AI-generated text in issues or PR descriptions except for minor grammar refinement, and clearly disclose AI tool usage in your PR. Non-compliant submissions or unreviewed AI output will be closed without review.

Development setup

1. Dev installation

Using pip (>= 25):

pip install --group dev -e .

Or using uv:

uv sync --group dev

2. Testing

Build the LicenseID licence database once (the licence-text detection tests skip or fail without it; a declared licence value is read without it), then run the test suite with pytest:

licenseid update --source packaged
pytest

The build is offline, from the SPDX License List the licenseid wheel ships. Rebuild it after upgrading licenseid: a database an older release built gives WARNING: licenseid: database: build ... outdated.

The conformance tests (tests/conformance/) need the conformance group, which the test and dev groups include.

3. Code quality

Python code must follow the PEP 8 style guide. Write fully typed code and include clear docstrings for all public modules, classes, functions, and methods (detailing arguments, returns, and exceptions).

Formatting, linting, and strict type checking form part of the project's quality gate and must pass before opening a pull request:

# Format and lint
ruff format examples/ src/ tests/
ruff check examples/ src/ tests/
flake8 examples/ src/ tests/
pylint examples/ src/ tests/ tests/*/

# Type checking
mypy examples/ src/ tests/
pyright examples/ src/ tests/
pyrefly check examples/ src/ tests/

# Security
bandit -r src/pitloom

CI runs these commands, with ruff format --check for formatting and Bandit in its own workflow (bandit.yaml).

4. Building the project

pip install build
python -m build

Architecture and project structure

Design documents

Internal, AI-agent-facing design and implementation notes live under working-docs/:

This guide is inspired by the Scikit-learn Contributing Guide