feat: add contribution guidelines

.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/]

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.

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)