Add CONTRIBUTING.md (#376)

* uv add --dev coverage

* Fix coverage report config

* Add Makefile

* Add CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing to magentic
+
+1. Fork and clone the repository
+2. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
+3. [Install pre-commit](https://pre-commit.com/#install)
+4. Run `make install` to install dependencies
+5. Run `make test` to run unit tests
+6. Run `make format` to format code
+7. Run `make lint` to lint code
+8. run `make docs` to build docs and `make docs-serve` to serve docs locally

Makefile

@@ -0,0 +1,50 @@
+# Adapted from https://github.com/pydantic/logfire/blob/main/Makefile
+
+.DEFAULT_GOAL := all
+
+.PHONY: .uv  # Check that uv is installed
+.uv:
+	@uv --version || echo 'Please install uv: https://docs.astral.sh/uv/getting-started/installation/'
+
+.PHONY: .pre-commit  # Check that pre-commit is installed
+.pre-commit:
+	@pre-commit -V || echo 'Please install pre-commit: https://pre-commit.com/'
+
+.PHONY: install  # Install the package, dependencies, and pre-commit for local development
+install: .uv .pre-commit
+	uv sync --frozen
+	pre-commit install --install-hooks
+
+.PHONY: format  # Format the code
+format:
+	uv run ruff format
+	uv run ruff check --fix
+
+.PHONY: lint  # Lint the code
+lint:
+	uv run ruff check
+	uv run ruff format --check --diff
+
+.PHONY: typecheck  # Typecheck the code
+typecheck:
+	uv run mypy .
+
+.PHONY: test  # Run the tests
+test:
+	uv run pytest -vv
+
+.PHONY: testcov  # Run tests and generate a coverage report
+testcov: test
+	@echo "building coverage html"
+	uv run coverage html --show-contexts
+
+.PHONY: docs  # Build the documentation
+docs:
+	uv run mkdocs build
+
+.PHONY: docs-serve  # Build and serve the documentation
+docs-serve:
+	uv run mkdocs serve
+
+.PHONY: all
+all: format lint test

pyproject.toml

@@ -34,6 +34,7 @@ dev = [
     "python-dotenv>=1.0.1",
     "ruff>=0.3",
     "pytest-recording>=0.13.2",
+    "coverage>=7.6.4",
 ]
 docs = [
     "blacken-docs>=1.16.0",
@@ -44,6 +45,10 @@ docs = [
 ]
 examples = ["ghapi>=1.0.5", "jupyter", "pandas>=2.2.1"]
 
+[tool.coverage.report]
+skip_covered = "true"
+show_missing = "true"
+
 [tool.mypy]
 check_untyped_defs = true
 disable_error_code = ["empty-body"]
@@ -65,7 +70,7 @@ venvPath = "."
 venv = ".venv"
 
 [tool.pytest.ini_options]
-addopts = "--cov=magentic --cov-report=term-missing --block-network"
+addopts = "--block-network --cov-report=html --cov-report=term --cov=magentic"
 asyncio_default_fixture_loop_scope = "function"
 asyncio_mode = "auto"
 markers = [