Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (66 loc) · 3.03 KB

CONTRIBUTING.md

File metadata and controls

105 lines (66 loc) · 3.03 KB
Raw

Contributing to Local CI

Thank you for your interest in contributing. This document is the onboarding entry point for development setup, testing, and pull requests.

Prerequisites

Before you start, install the runtime tools listed in the README:

Tool Notes
Python 3.10+ CLI runtime
Docker Container execution (Linux containers)
act Run GitHub Actions locally
mikefarah/yq v4+ Required — see below

yq (read this first)

Local CI requires mikefarah/yq v4+. Disambiguation, per-OS install commands, and verification: README — yq (mikefarah/yq v4 or newer).

Development setup

All Python work happens under cli/:

cd cli
pip install -e ".[dev]"

The [dev] extra installs pytest, ruff, mypy, pre-commit, and type stubs (cli/pyproject.toml).

Optional — install git hooks so lint and typecheck run before each commit:

pre-commit install

Hooks are defined in .pre-commit-config.yaml and mirror the CI lint and typecheck jobs.

Running tests

From cli/:

pytest

This runs unit tests under tests/ and excludes tests/integration/ by default (norecursedirs in pyproject.toml). CI runs the same default set with coverage:

pytest --cov=localci --cov-report=term-missing -m "not integration"

Integration tests (opt-in)

Integration tests exercise real act and Docker subprocesses. They require both tools installed and a running Docker daemon. When unavailable, the suite skips automatically.

To run them locally:

pytest tests/integration -m integration -v

CI runs integration tests in a separate job after lint, typecheck, and unit tests pass (see .github/workflows/ci.yml).

Linting and formatting

From cli/:

ruff check localci/ tests/
ruff format localci/ tests/

Ruff configuration lives in cli/pyproject.toml ([tool.ruff]).

Type checking

From cli/:

mypy localci/

Mypy runs in strict mode. Legacy CLI modules are temporarily suppressed via per-module overrides; localci.core.* and localci.utils.* must pass strict typing. Do not add new modules to the ignore_errors list.

Pre-commit

Run all hooks against the full tree (useful before pushing):

pre-commit run -a

Pull requests

  1. Branch from develop (or main for release fixes).
  2. Keep changes focused; link related issues in the PR description.
  3. Ensure CI is green — lint, typecheck, unit tests, and integration tests must pass.
  4. Request review from at least one maintainer. PRs need at least one approving review before merge.

Maintainers

Current maintainer: @bradjin8 (see .github/CODEOWNERS).

For usage questions and configuration, see the User Guide.