CONTRIBUTING.md

Created	2026-07-08
Last-Modified	2026-08-10
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

Run the test suite with pytest:

pytest

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 & lint with Ruff
ruff format
ruff check src/ tests/

# Type-checking & strict linting
mypy src/
pyright src/
pyrefly check src/
pylint examples/ src/ tests/ tests/*/

4. Building the project

pip install build
python -m build

---

Architecture and project structure

• Project tree: See working-docs/implementation/summary.md for the canonical structure.
• Roadmap: See working-docs/design/roadmap.md to see what is planned next.

Design documents

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

• Architecture overview — Overall system design.
• Adoption surfaces — How Pitloom's surfaces (CLI, API, build hook, Action, Skills, plugin) fit together.
• Metadata provenance — Provenance tracking design.
• Release checklist — Maintainer-facing steps for cutting a release, including verifying the wheel-embedded SBOM on the actual PyPI-published artifact.
• Browse the design/ and implementation/ directories for the full documentation set.

---

This guide is inspired by the Scikit-learn Contributing Guide