Skip to content

contributing.md

Latest commit

 

History

History
117 lines (79 loc) · 3.4 KB

contributing.md

File metadata and controls

117 lines (79 loc) · 3.4 KB

Contributing to oblt-aw

Overview

This guide covers local setup and quality checks for contributors. All changes must pass CI before merge.

Prerequisites

One-time Setup

1. Install pre-commit

pip install pre-commit
# or: brew install pre-commit

2. Install pre-commit hooks

pre-commit install

This installs the hooks from .pre-commit-config.yaml. They run automatically on git commit.

3. Install Python dependencies

pip install pytest==9.0.2

4. Install Node.js dependencies

npm ci

Running Checks Locally

All pre-commit hooks (recommended before pushing)

pre-commit run --all-files

macOS Python.org installer: If you see SSL: CERTIFICATE_VERIFY_FAILED when pre-commit installs hooks, this is the classic Python.org macOS certificate issue. Run the bundled installer: /Applications/Python 3.xx/Install Certificates.command

Python tests

pytest tests/ -v --tb=short

TypeScript tests

npm test

License automation

Update license headers and NOTICE files:

make update-license
# or: python3 scripts/update_license_files.py

Verify without modifying (useful for CI):

make update-license-check
# or: python3 scripts/update_license_files.py --check

License headers are not applied to *.yml or *.yaml files (including GitHub Actions workflows).

The update-license-files hook uses always_run: true in .pre-commit-config.yaml so the script runs on every pre-commit invocation and rescans all header targets (not only when certain file types are staged).

Individual tools

  • YAML lint: yamllint . (uses .yamllint.yml)
  • Shell lint: find scripts tests -type f -name '*.sh' -print0 | xargs -0 shellcheck
  • GitHub Actions lint: actionlint
  • Python lint: ruff check .
  • Python format: ruff format --check .
  • Python type-check: mypy --strict scripts/
  • GitHub Actions lint: actionlint

Pre-commit Hooks

The following hooks run on commit (and in CI via the pre-commit job):

Hook Scope Purpose
yamllint *.yml, *.yaml YAML style and structure
shellcheck Shell scripts Shell script linting
actionlint GitHub Actions workflows GitHub Actions workflow linting
ruff Python files (repo-wide) Python lint (with --fix)
ruff-format Python files (repo-wide) Python formatting
mypy scripts/**/*.py Python type-checking (strict)
update-license-files Scripts, shell, TypeScript tests, NOTICE Apache 2.0 headers, NOTICE sync
pre-commit-hooks Various Trailing whitespace, EOF, etc.

CI Workflow

The CI workflow (.github/workflows/ci.yml) runs on every PR to main. See docs/workflows/ci.md for details.

References