Add CONTRIBUTING, CHANGELOG, and CODEOWNERS; centralize yq onboarding (closes #71)

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default reviewers for all paths.
+* @bradjin8 @wpak-ai

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

CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# 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)
+
+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
+
+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).

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