Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (89 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

112 lines (89 loc) · 5.47 KB
Raw

Contributing

Thanks for your interest in method-kit. This repository ships a transverse methodology: the METHOD.md operating method and the project-pilot skill suite — one installable container that bundles the procedural tools as modules, with the steering-doc templates and the bootstrap runbook as its resources. Most code is pure standard library; the quality/security tooling (ruff, bandit) is declared as PEP 735 dependency-groups in pyproject.toml, pinned to exact versions — there is no requirements.txt manifest.

This guide is for two audiences:

  • Contributors who want to propose a change via a pull request.
  • Forkers who want to run their own version. For forks, also read CI_CD.md, which explains which protections live in files (and travel with a fork) and which live in repository settings (and do not).

Ground rules

main is the protected trunk: every change is meant to land through a pull request that passes the required checks (quality, tests, security, docs-privacy, Analyze (python)).

Honest note on enforcement: on this repository's current tier, the Layer-B settings that enforce the rule (branch protection + the code-scanning ruleset) are defined in files but not yet active — the GitHub API rejects them on a free private repo (see CI_CD.md §5–§6). The workflows still run and report on every pull request, and the gated-PR rule is held by discipline until Layer B is activated. Treat the gates as required.

Prerequisites

  • Python 3.12 (the version CI runs on).
  • The quality/security tools, installed from the dev dependency-group so your local versions match CI exactly (needs pip >= 25.1 for PEP 735):
python -m pip install --upgrade pip;
python -m pip install --group dev

The dev group pulls ruff==0.15.18, bandit[toml]==1.9.4, pytest==9.1.1, defusedxml==0.7.1, and — on Windows — tzdata (which zoneinfo needs there). defusedxml is a runtime dependency of the diagram checker (declared in its module requirements.txt); the tests floor imports it. A virtual environment is recommended but not required.

Reproduce the gates locally (before you push)

Run the same checks CI runs, from the repository root. If they pass locally, your pull request will go green on the first try.

bash scripts/gates/quality.sh;
bash scripts/gates/tests.sh;
bash scripts/gates/security.sh

Notes:

  • ruff format --check . only reports; to apply formatting run ruff format ..
  • ruff/bandit scan the whole repository (.venv is excluded by the ruff config).
  • The tests gate runs the module floors (exit 0/1, pure standard library), auto-discovered by scripts/discover_floors.py --run — adding a module drops a # FLOOR script and the gate finds it. It then runs pytest tests/; the first non-zero exit fails the check.
  • On Windows, scripts/gates/tests.sh exports PYTHONUTF8=1 before the floors run, so the steering-docs floor can print status glyphs (🟢/🟡/⬜) the default cp1252 console cannot encode. CI (Ubuntu) is UTF-8 and needs no prefix.
  • Analyze (python) (CodeQL) runs in CI only — it is not reproducible locally.

Pull request workflow

flowchart LR
    F["Fork or branch"] --> L["Run gates locally<br/>ruff &middot; bandit &middot; compile &middot; floors"]
    L --> PR["Open a PR to main"]
    PR --> C{"quality &middot; tests &middot; security &middot; docs-privacy &middot; Analyze (python)<br/>all green? branch up to date?"}
    C -- yes --> M(["Squash-merge"])
    C -- no --> Fix["Fix and push again"]
    Fix --> C
Loading
  1. Fork the repository (or, if you have write access, create a branch).
  2. Create a topic branch, e.g. git checkout -b fix/short-description.
  3. Make your change and run the gates locally (above).
  4. Commit and push your branch, then open a pull request targeting main.
  5. Wait for the required checks to pass:
    • quality — ruff lint + format, projected-doc drift (doc-drift), and the compileall sweep over skills/.
    • security — Bandit security scan.
    • tests — the auto-discovered module floors plus pytest tests/.
    • docs-privacy — private-marker scan over docs/**.
    • Analyze (python) — CodeQL semantic security analysis.
  6. Your branch must be up to date with main before merging.
  7. Once Layer B is active, a merge is also blocked if CodeQL reports a code-scanning alert at or above the configured threshold (security severity High+, or any error).

The full description of each gate is in CI_CD.md.

Commit conventions

  • Use a short, conventional prefix: ci:, docs:, fix:, feat:, chore:. (No deps: — no pip manifest is tracked; CI action pins are full SHAs, re-pinned by hand when the action-drift watcher flags an upstream tag move.)
  • Keep one family of changes per pull request; documentation accompanies the change it describes.
  • Consider committing with a GitHub noreply email to avoid leaking a real address in public history.

What not to commit

  • No personal data. Names, addresses, real CVs, real company names — all fixtures and examples must be fictional.
  • No build artifacts. dist/ is git-ignored; the release workflow builds and publishes it on a v* tag push.