diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..e28e3e5 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,29 @@ +# Pre-commit hooks mirroring Fair Code CI. See CONTRIBUTING.md. +# One-time install: pre-commit install +# Run against the whole repo: pre-commit run --all-files +default_install_hook_types: [pre-commit, pre-push] + +repos: + - repo: local + hooks: + - id: em-dash + name: em-dash-free check + entry: python3 scripts/check_em_dash.py + language: system + pass_filenames: false + always_run: true + + - id: build-explainers + name: regenerate explainer pages + entry: python3 scripts/build_explainers.py + language: system + pass_filenames: false + files: '^(explainers/.*\.md|assets/explainers-data\.json)$' + + - id: pytest + name: pytest (full suite) + entry: python3 -m pytest tests/ -q + language: system + pass_filenames: false + always_run: true + stages: [pre-push] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd06a46..a8f59d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,6 +60,28 @@ If you are unsure whether an idea fits, open an issue first and ask. --- +## Local setup and checks + +A `Makefile` and a `.pre-commit-config.yaml` reproduce what CI runs, so you can catch failures before you open a PR: + +```bash +make setup # install faircode + pytest + pre-commit +make check # everything CI runs: em-dash lint + full test suite +make test # just the test suite +make build-explainers # regenerate explainer pages after editing explainers/*.md +make lint # em-dash-free check only +``` + +Optionally install the git hooks so the checks run automatically: + +```bash +pre-commit install +``` + +With the hooks installed, the em-dash lint runs on every commit (and explainer pages rebuild when you touch `explainers/*.md`), while the full test suite runs on `git push`. Run `make check` any time to reproduce CI on demand. + +--- + ## 1. Before you start - Read the relevant section in this guide before writing code. @@ -463,4 +485,4 @@ Include in the PR description: --- -All datasets used in this project are publicly available. Fair Code is for educational and awareness purposes. \ No newline at end of file +All datasets used in this project are publicly available. Fair Code is for educational and awareness purposes. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..0b43356 --- /dev/null +++ b/Makefile @@ -0,0 +1,27 @@ +# Fair Code - contributor task runner. See CONTRIBUTING.md. +# Reproduces locally what CI runs (.github/workflows: audits.yml, lint.yml, +# build-explainers.yml) so you can catch failures before you push. + +.DEFAULT_GOAL := help +PY := python3 + +.PHONY: help setup test build-explainers lint check + +help: ## Show the available targets + @grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | \ + awk 'BEGIN{FS = ":.*?## "}{printf " %-16s %s\n", $$1, $$2}' + +setup: ## Install the package plus the dev tools (pytest, pre-commit) + $(PY) -m pip install -e . pytest pre-commit + +test: ## Run the full test suite (mirrors CI) + $(PY) -m pytest tests/ -q + +build-explainers: ## Regenerate explainer pages, data.js, and sitemap + $(PY) scripts/build_explainers.py + +lint: ## Enforce the em-dash-free rule (mirrors the lint workflow) + $(PY) scripts/check_em_dash.py + +check: lint test ## Run everything CI runs (em-dash lint + full test suite) + @echo "All checks passed."