From e4754891a3283c9baf95ae1e99e81b155fa4807b Mon Sep 17 00:00:00 2001 From: Imran Siddique Date: Mon, 7 Sep 2026 21:50:39 -0700 Subject: [PATCH] docs: add contribution guidance This repo is public and told a would-be contributor nothing: no CONTRIBUTING.md, no contribution section in the README, and no org-level default to fall back on. The substance is the one rule that matters here. A demo prints claims about what was enforced, denied or verified, and a reader believes them, so the script must check the thing it claims and fail loudly when the check fails. We have shipped the opposite once already: demo-06 printed "gate released key: False" under a heading saying the opposite. That is now written down as the bar for a merge, along with exiting non-zero on a failed assertion so CI catches it, and adding any new demo to ci.yml so it actually runs. Claims in the file were checked against the repo: requirements.txt exists and is what the README installs, tests/ exists, and ci.yml runs eight demos. Also clears the OpenSSF Best Practices criteria for contribution information, which is what surfaced the gap. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01XbDBXDWWvMFa7c2jGgyq9t --- CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7dea0bc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing + +Thanks for looking. This repository holds runnable demos for cMCP, TRACE and the +agent governance tooling. Everything here is meant to be executed rather than only read, +which shapes what a good contribution looks like. + +## Getting the code and running it + +``` +git clone https://github.com/agentrust-io/demos +cd demos +pip install -r requirements.txt +python demo-01-cmcp-in-action/run.py +``` + +The README lists every demo and roughly how long each takes. CI runs all of them +on every pull request, so if a demo does not run from a clean checkout, that is a +bug worth reporting. + +## Reporting a problem or suggesting a demo + +Open an issue: . For a broken demo, +include the command you ran and what it printed. The output is the evidence. + +For a security issue, do not open an issue. See [SECURITY.md](SECURITY.md). + +## What an acceptable contribution looks like + +**A demo must assert its own outcome.** This is the one rule worth stating +plainly. A demo prints claims about what was enforced, denied, or verified, and a +reader believes them. So the script must check the thing it claims and fail +loudly when the check fails. Printing a heading and then printing a value that +contradicts it is the specific failure mode we have already shipped once: demo-06 +printed `gate released key: False` under a heading saying the opposite. A demo +that can print a success message while the underlying check failed is not +finished. + +Concretely, for a change to be merged: + +- The demo runs end to end from a clean checkout with the documented command. +- It exits non-zero when its own assertion fails, so CI catches it. +- Its output states what actually happened, including when that is a denial. +- Any new demo is added to the README with what it shows and how long it takes, + and to `.github/workflows/ci.yml` so it is run on every pull request. +- Tests under `tests/` cover any shared helper you add. + +## Style + +- Match the surrounding code. There is no separate style guide to learn. +- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org), + e.g. `fix(demo-06): assert the gate result the heading claims`. +- Keep pull requests small and single-purpose. + +## Fixtures and keys + +Everything committed here is synthetic. Sample keys and fixtures exist to be +published and are not secrets. Never add a real credential, endpoint or customer +identifier, even in a comment. + +## Licence + +By contributing you agree that your contribution is licensed under the MIT +Licence in [LICENSE](LICENSE), the same terms as the rest of the repository.