From 1566a1e0eb4a7cd38f6edb2b938e23b57e6f750f Mon Sep 17 00:00:00 2001 From: bradjin8 Date: Thu, 9 Jul 2026 15:28:16 -0400 Subject: [PATCH 1/2] initial implementation of #71 --- .github/CODEOWNERS | 2 + CHANGELOG.md | 39 +++++++++++++++ CONTRIBUTING.md | 116 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 4 files changed, 159 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..287b2fa --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Default reviewers for all paths. +* @bradjin8 @wpak-ai diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..78b3f74 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,39 @@ +# Changelog + +All notable changes to this project are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- `CONTRIBUTING.md` — developer onboarding (setup, tests, lint, pre-commit, PR expectations) +- `CHANGELOG.md` — this file +- `.github/CODEOWNERS` — maintainer routing for reviews + +## [0.1.0] - TBD + +Pre-release baseline. The CLI package version is `0.1.0` (`cli/pyproject.toml`). + +### Added + +- `localci` CLI — analyze, list, run, status, logs, images, cache, and config commands +- Configurable workflow patch pipeline for local act execution +- Docker image management and caching (ccache, Boost, CMake, APT) +- CI: ruff lint/format, mypy strict typecheck, unit tests, and act/Docker integration tests +- Runnable validation example under `examples/` +- README yq disambiguation and per-OS install matrix for [mikefarah/yq](https://github.com/mikefarah/yq) v4+ + +### Pre-release stability (before 1.0) + +This project is in **0.x** pre-release. Until **1.0.0**: + +- **No stability guarantee** — public CLI flags, config schema (`.localci.yml`), and patch-pipeline behavior may change between minor releases without a major-version bump. +- **Config and workflow patches** — projects depending on specific patch steps or defaults should pin a `localci` version and read the changelog before upgrading. +- **Bug fixes and internal refactors** — may land on `develop` without a deprecation period. +- **1.0 intent** — a stable CLI surface, documented config compatibility policy, and semver guarantees for config and command-line interfaces. + +[Unreleased]: https://github.com/cppalliance/local-ci-test-system/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/cppalliance/local-ci-test-system/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ff6001b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,116 @@ +# 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](README.md#prerequisites): + +| Tool | Notes | +|------|-------| +| Python 3.10+ | CLI runtime | +| Docker | Container execution (Linux containers) | +| [act](https://github.com/nektos/act) | Run GitHub Actions locally | +| **[mikefarah/yq v4+](https://github.com/mikefarah/yq)** | **Required** — see below | + +### yq (read this first) + +Several incompatible tools share the name `yq`. Local CI requires **[mikefarah/yq v4+](https://github.com/mikefarah/yq)** — **not** the PyPI `yq` package and **not** [kislyuk/yq](https://github.com/kislyuk/yq). Installing the wrong tool causes unclear runtime failures. + +**→ Full disambiguation table and per-OS install commands: [README — yq (mikefarah/yq v4 or newer)](README.md#yq-mikefarahyq-v4-or-newer)** + +Verify your install: + +```bash +yq --version +# Should reference mikefarah / github.com/mikefarah or report version v4+ +``` + +If no suitable binary is on `PATH`, the CLI falls back to PyYAML with limited expression support and emits a warning (`localci.utils.yq`). + +## Development setup + +All Python work happens under `cli/`: + +```bash +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: + +```bash +pre-commit install +``` + +Hooks are defined in [`.pre-commit-config.yaml`](.pre-commit-config.yaml) and mirror the CI lint and typecheck jobs. + +## Running tests + +From `cli/`: + +```bash +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: + +```bash +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: + +```bash +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`](.github/workflows/ci.yml)). + +## Linting and formatting + +From `cli/`: + +```bash +ruff check localci/ tests/ +ruff format localci/ tests/ +``` + +Ruff configuration lives in [`cli/pyproject.toml`](cli/pyproject.toml) (`[tool.ruff]`). + +## Type checking + +From `cli/`: + +```bash +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): + +```bash +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](https://github.com/bradjin8) (see [`.github/CODEOWNERS`](.github/CODEOWNERS)). + +For usage questions and configuration, see the [User Guide](cli/Usage%20Guide.md). diff --git a/README.md b/README.md index 880c198..23ae90f 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,8 @@ local-ci-test-system/ ## Documentation +- **[Contributing](CONTRIBUTING.md)** — Developer setup, tests, lint, pre-commit, and PR expectations (includes [yq prerequisite](README.md#yq-mikefarahyq-v4-or-newer) onboarding) +- **[Changelog](CHANGELOG.md)** — Release history and pre-1.0 stability notes - **[User Guide](cli/Usage%20Guide.md)** — Installation, configuration, commands, troubleshooting (includes [workflow patch pipeline](cli/Usage%20Guide.md#workflow-patch-pipeline) and plugin registration) - **[Design Guide](docs/Design%20Guide.md)** — Architecture and caching - **[Performance and Caching](docs/Performance%20and%20Caching.md)** — Cache layout and config From 6744850f1815e4dc681a86e79c141f5df3ad5de1 Mon Sep 17 00:00:00 2001 From: bradjin8 Date: Thu, 9 Jul 2026 15:48:58 -0400 Subject: [PATCH 2/2] fix: nitpick comment --- CONTRIBUTING.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff6001b..54eeb2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,18 +15,7 @@ Before you start, install the runtime tools listed in the [README](README.md#pre ### yq (read this first) -Several incompatible tools share the name `yq`. Local CI requires **[mikefarah/yq v4+](https://github.com/mikefarah/yq)** — **not** the PyPI `yq` package and **not** [kislyuk/yq](https://github.com/kislyuk/yq). Installing the wrong tool causes unclear runtime failures. - -**→ Full disambiguation table and per-OS install commands: [README — yq (mikefarah/yq v4 or newer)](README.md#yq-mikefarahyq-v4-or-newer)** - -Verify your install: - -```bash -yq --version -# Should reference mikefarah / github.com/mikefarah or report version v4+ -``` - -If no suitable binary is on `PATH`, the CLI falls back to PyYAML with limited expression support and emits a warning (`localci.utils.yq`). +Local CI requires **[mikefarah/yq v4+](https://github.com/mikefarah/yq)**. Disambiguation, per-OS install commands, and verification: [README — yq (mikefarah/yq v4 or newer)](README.md#yq-mikefarahyq-v4-or-newer). ## Development setup