Docs/contributing test instructions

[kami619]

Description

This helps new contributors understand how to set up their development environment and run tests before submitting PRs.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Related Issues

NA

Changes Made

• Prerequisites: Python 3.10+, uv/pip, Git
• Development Setup: Add venv creation and package installation commands
• Running Tests: Document make test, pytest commands, and common options
• Code Style: Document black, isort, ruff and make lint/format commands

Testing

• Unit tests pass (pytest)
• Integration tests pass
• Manual testing performed
• No new warnings or errors

Checklist

• My code follows the project's code style
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

[github-actions]

📈 Test Coverage Report

Branch	Coverage
This PR	66.0%
Main	66.0%
Diff	✅ +0%

---

Coverage calculated from unit tests only

[github-actions]

Code Review: Docs/contributing test instructions

Overall: Good improvement to onboarding documentation. One critical factual error that must be fixed before merge.

---

Issues

1. Critical: Python Version Is Wrong

CONTRIBUTING.md line 13

- Python 3.10 or higher

This is incorrect. pyproject.toml requires >=3.12 — contributors setting up Python 3.10 or 3.11 will encounter installation failures. Must be:

- Python 3.12 or higher

(Note: CLAUDE.md also incorrectly states "Python 3.11+" — but that's out of scope for this PR.)

2. dnf install uv Does Not Work on RHEL/CentOS

CONTRIBUTING.md lines 19-23

The heading reads "Fedora/RHEL/CentOS (dnf)" but uv is only available in Fedora repos (Fedora 40+), not in RHEL or CentOS repos. Running dnf install uv on RHEL 9 or CentOS Stream will fail with "No match for argument: uv".

Options:

• Narrow the heading to "Fedora (dnf)"
• Or replace with the universal installer that works across all Linux distros: curl -LsSf https://astral.sh/uv/install.sh | sh

3. Trailing Empty Line in Code Block (cosmetic)

The dev setup bash block has an extra blank line before the closing backticks.

---

Strengths

• uv pip install -e ".[dev]" correctly uses the [dev] extras defined in pyproject.toml — better than the approach in CLAUDE.md which installs dev tools as a separate step.
• make test, make test-coverage, make lint, make format all exist in the Makefile — documented commands are accurate.
• Documenting pytest tests/unit/ and pytest tests/e2e/ separately is helpful for contributors working on targeted changes.

---

Summary

Fix the Python version prerequisite (3.12, not 3.10) before merging — contributors will otherwise have a broken setup experience.

[github-actions]

AgentReady Code Review: PR #307 — Docs/contributing test instructions

Reviewer: Claude Code (review-agentready)
Scope: CONTRIBUTING.md (+75 lines, 0 deletions)

---

AgentReady Attribute Compliance

This PR fills in three previously empty sections of CONTRIBUTING.md (Prerequisites, Running Tests, Code Style), which directly improves the following AgentReady attributes:

Attribute	Before PR	After PR	Impact
Contributing guide completeness	Empty stubs (gaps)	Actionable, verified content	+Score
Onboarding documentation	No setup instructions	Full venv + install workflow	+Score
Test documentation	Blank section	make commands + pytest variants	+Score

The self-assessment score (currently 80.0/100 Gold) should benefit from the improved contributing guide coverage.

---

Factual Accuracy — All Verified Against Codebase

Claim in PR	Source of Truth	Status
Python 3.12+	pyproject.toml: requires-python = ">=3.12"	✅ Correct
uv pip install -e ".[dev]"	pyproject.toml has [project.optional-dependencies] dev = [...]	✅ Correct
make test	Makefile: test: pytest	✅ Correct
make test-coverage	Makefile: test-coverage: pytest --cov=...	✅ Correct
make lint	Makefile: lint: ruff check ... && black --check ... && isort --check-only ...	✅ Correct
make format	Makefile: format: black ... && isort ...	✅ Correct
pytest tests/unit/	tests/unit/ exists	✅ Correct
pytest tests/e2e/	tests/e2e/ exists	✅ Correct
tests/unit/cli/test_main.py::TestRunAssessment	Class confirmed in file	✅ Correct

---

Issues

1. Stale Dev Dependency: flake8 Not Documented (Minor)

pyproject.toml includes flake8>=6.0.0 in the [dev] extras, but the Code Style section only documents black, isort, and ruff. The Makefile's lint target also does not invoke flake8. This creates a silent dependency that installs but is never used.

Recommendation: Either remove flake8 from [project.optional-dependencies].dev in pyproject.toml (since ruff is a strict superset), or document it. Out of scope for this PR but worth a follow-up.

2. Trailing Blank Line in Code Block (Cosmetic)

The dev setup block has a stray empty line before the closing triple-backtick.

No functional impact, but inconsistent with the other code blocks in the file.

3. pip install uv for "Other Platforms" Creates a Bootstrap Dependency (Minor)

Using pip install uv requires the contributor to already have a working pip. On fresh systems (e.g., Docker, minimal Linux) where pip may not be present, the uv universal installer is more reliable:

curl -LsSf https://astral.sh/uv/install.sh | sh

The current approach works fine for most contributors and is simpler, but worth considering.

---

Security

No security concerns. This is a pure documentation change with no code execution paths, no credential handling, and no external service calls introduced.

---

Strengths

• Fills critical gaps: The three previously blank sections (Prerequisites, Running Tests, Code Style) left contributors without actionable guidance. This PR fixes that directly.
• [dev] extras correctly used: uv pip install -e ".[dev]" is more idiomatic than the approach in CLAUDE.md which installs dev tools as a separate step.
• Platform coverage: macOS (Homebrew), Fedora 40+ (dnf), and generic fallback all addressed.
• Granular pytest examples: Showing file, class, and function-level :: selectors helps contributors run targeted tests efficiently.

---

Verdict

Approve with minor notes. The two actionable items (trailing blank line, flake8 staleness) can be addressed in this PR or as follow-ups. Neither blocks merge. The core content is accurate and a meaningful improvement to contributor onboarding.

---

[github-actions]

🎉 This PR is included in version 2.28.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀