diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 714daf6..b79d668 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -30,8 +30,12 @@ repos: - id: ruff-check args: [--fix] - id: ruff-format - - repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.15.0 + - repo: local hooks: - id: mypy - additional_dependencies: [] + name: mypy + entry: uv run --frozen mypy + language: system + types: [python] + pass_filenames: false + args: [src/] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3c8bdf6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,79 @@ +# Contributing to model2vec + +Thanks for your interest in model2vec. This document explains how contributions work and what we expect. + +## tl;dr + +- **Every PR must link to an existing issue.** Open an issue to discuss before writing code, then link it from your PR (e.g. `Closes #123`). +- **AI-generated PRs** will be closed without review if they weren't discussed beforehand. + +--- + +## Discuss before building + +Our libraries are small and focused by design. We care a lot about keeping it that way. Before you invest time writing code, please open an issue describing: + +- What problem you're solving +- Why it belongs in model2vec (as opposed to a wrapper or separate tool) +- What API or behaviour change it would involve, if any +- A minimal (code) example of how it would work + +This applies to small PRs (e.g. bug fixes and documentation updates) as well. A quick issue lets us confirm the fix is wanted and aligned with how we'd want to solve it, so you don't waste time on a PR we'd need to reject or rework. + +**PRs without a linked issue will be closed.** + +## What we generally welcome + +- Bug fixes (with a linked issue and a test that reproduces the issue) +- Documentation improvements and example fixes (with a linked issue) + +## What we generally won't accept + +- Large new features that haven't been discussed +- Features that significantly expand the scope of the library +- Dependency additions +- AI-generated code dumps with no context or discussion + +## Opening a good issue + +If you found a bug, include: +- model2vec version +- Python version +- A minimal reproducible example +- What you expected vs. what happened + +If you want a feature, include the things listed under "Discuss before building" above. + +## Pull request checklist + +Before opening a PR: + +- [ ] Link to an existing issue (e.g. `Closes #123`). PRs without one will be closed +- [ ] Run `make test` and confirm all tests pass +- [ ] Run `make lint` and `make typecheck` +- [ ] Run `make fix` to auto-fix any lint issues +- [ ] If you added behaviour, add or update tests +- [ ] If you changed a public API, update the docstrings +- [ ] Keep the diff focused (one logical change per PR) + +You can also run `make pre-commit` to run all checks at once. + +## Code style + +- We use `ruff` for formatting and linting +- We use `mypy` for type checking and expect all new code to be fully typed +- Keep things simple; we prefer readable over clever + +## A note on AI-assisted contributions + +We don't have a blanket policy against AI tools (we also use them ourselves). But we do expect: + +1. **You understand what you're submitting.** If you ran an agent against the repo and opened a PR with the output, you should be able to explain what it does. +2. **The contribution was discussed first.** An AI generating code for an agreed-on, well-scoped issue is fine. An AI inventing features and opening a PR is not. +3. **Tests and quality are your responsibility.** "The AI wrote it" is not a substitute for correctness. + +PRs that appear to be unreviewed AI output (large scope, multiple unrelated files touched, no prior discussion, new deps) will be closed with a pointer to this document. + +--- + +Questions? Open an issue. diff --git a/Makefile b/Makefile index 0b03d1d..1c0bfac 100644 --- a/Makefile +++ b/Makefile @@ -1,27 +1,45 @@ -VERBOSITY= - -venv: - uv venv - -install: - uv sync --all-extras +.PHONY: help install install-no-pre-commit install-base test test-integration test-integration-update test-integration-pretrained-update lint typecheck fix pre-commit + +help: + @echo "Available targets:" + @echo " install Install all dependencies and pre-commit hooks" + @echo " install-no-pre-commit Install all dependencies without pre-commit hooks" + @echo " install-base Install only the dev dependencies" + @echo " test Run unit tests with coverage (excludes integration tests)" + @echo " test-integration Run integration tests" + @echo " test-integration-update Regenerate the distill integration baseline" + @echo " test-integration-pretrained-update Regenerate the pretrained integration baseline" + @echo " lint Run ruff and pydoclint" + @echo " typecheck Run mypy" + @echo " fix Auto-fix lint issues and format code" + @echo " pre-commit Run all pre-commit hooks" + +install: install-no-pre-commit uv run pre-commit install install-no-pre-commit: - uv pip install ".[dev,distill,train,onnx,quantization,integration,tests]" + uv sync --all-extras install-base: uv sync --extra dev +lint: + uv run ruff check model2vec/ tests/ + uv run pydoclint model2vec/ + +typecheck: + uv run mypy model2vec/ + fix: + uv run ruff check --fix model2vec/ tests/ + uv run ruff format model2vec/ tests/ + +pre-commit: uv run pre-commit run --all-files test: uv run pytest --cov=model2vec --cov-report=term-missing --ignore=tests/integration $(VERBOSITY) -test-verbose: - make test VERBOSITY="-vvv" - test-integration: uv run pytest tests/integration $(VERBOSITY)