Skip to content

Add CONTRIBUTING + CHANGELOG governance docs and centralize yq onboarding #71

Description

@bradjin8

Problem

The repository has no CONTRIBUTING, CHANGELOG, GOVERNANCE, CODEOWNERS, or CODE_OF_CONDUCT file (confirmed: none tracked in git). For a pre-release project (version = "0.1.0", pyproject.toml:7) maintained by a single contributor, this leaves no documented onboarding path, no stability/compat commitment, and no record of changes — the sustainability risk flagged by the eval. The related "yq is ambiguous among three tools" hazard (pip yq vs kislyuk/yq vs the required mikefarah/yq v4+) is already substantially mitigated: README.md:16-39 has a dedicated disambiguation table and per-OS install matrix, and cli/localci/utils/yq.py detects the flavour at runtime (_detect_yq_flavour, lines 101-127) and warns on fallback (_warn_pyyaml_fallback, lines 89-99). The remaining gap is that this critical prerequisite is documented only in the README/runtime warnings and is not surfaced in a contributor onboarding doc — new contributors have no single entry point that points them at it alongside build/test/lint setup.

Acceptance Criteria

  • A CONTRIBUTING.md is added covering: dev setup (cd cli && pip install -e ".[dev]"), running tests (pytest, plus the integration marker), linting/typing (ruff, mypy localci/), pre-commit (.pre-commit-config.yaml), and the PR/review expectations
  • CONTRIBUTING.md surfaces the mikefarah/yq v4+ prerequisite in the onboarding path (linking to, not duplicating, the README disambiguation at README.md:29-39) so the hazard is unmissable for new contributors
  • A CHANGELOG.md is added (Keep a Changelog style) with an Unreleased section and the current 0.1.0 baseline, plus a short pre-release stability note (what compat guarantees exist before 1.0)
  • Docs cross-link: README.md's Documentation section (lines 117-122) links to the new CONTRIBUTING.md and CHANGELOG.md
  • (Optional, if desired for bus-factor) a CODEOWNERS and/or brief maintainership note is added naming the current owner
  • Tests pass in CI (if applicable)
  • PR approved by at least 1 reviewer

Implementation Notes

  • New files at repo root: CONTRIBUTING.md, CHANGELOG.md (and optionally .github/CODEOWNERS). No source changes required.
  • Do not re-document the yq disambiguation from scratch — it already exists and is good (README.md:16-39). Link to it; the value here is putting a pointer in the contributor onboarding flow, not duplicating content.
  • Pull dev-workflow specifics from existing sources to keep the CONTRIBUTING accurate: dev extra and tool config in cli/pyproject.toml ([project.optional-dependencies].dev lines 20-29, [tool.pytest.ini_options] lines 37-43, [tool.ruff] lines 80-90), and the hooks in .pre-commit-config.yaml.
  • Gotcha: the integration pytest marker requires act + Docker and is excluded by default (norecursedirs = ["integration"], pyproject.toml:43) — document how to opt into running it so contributors don't think integration tests are missing.
  • This directly addresses the single-contributor / bus-factor-of-one sustainability finding by lowering the barrier for a second contributor to onboard and by recording change history.

References

  • Eval finding: Test 28 (onboarding) — "yq dependency name ambiguity blocks onboarding"; Test 38 (sustainability) — "Single-contributor maintenance constraint" / "No changelog or stability commitment for pre-release"
  • Related files: README.md, cli/localci/utils/yq.py, cli/pyproject.toml, .pre-commit-config.yaml

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions