crossbario / crossbario/autobahn-python
[CHORE] Refresh CONTRIBUTING.md: document issue-first + AI-disclosure (.audit) requirements; fix stale tox/paths
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 768
- PR merge metrics
- No merged PRs in 30d
Description
Why
CONTRIBUTING.md is both incomplete (it omits requirements we actually
enforce) and stale (it references tooling/paths we no longer use). PR #1887
is a good example: the contributor followed the public guide, but tripped over
process rules that are only written down in AI_POLICY.md / .ai /
.audit/AI_AUDIT_PROCESS.md, not in CONTRIBUTING.md. Let's make the public
guide match reality so external contributors can succeed first time.
Missing — add these
- Issue-first workflow. State that every change starts from a GitHub
issue, and the PR must reference it (Closes #<issue>). The current
"Contributing Code" list jumps straight to fork/branch. - AI-assistance disclosure. Document that every PR must include a
disclosure file at.audit/<github-username>_<branch>.md(e.g.
.audit/bblommers_websocket-server-typing.md), not a PR comment. Link
.audit/AI_AUDIT_PROCESS.md
andAI_POLICY.md. (This is the biggest gap — currently undocumented.) - Branch guidance. Note the
fix_<issue>convention for maintainers,
while making clear descriptive branch names from external forks are welcome
(e.g.patch-1).
Stale — fix these
- Test runner. Replace the
tox/tox -e py312section with the
currentjustrecipes (just test,just check, etc.). - Test path.
pytest autobahn/test/test_websocket.py→ src-layout
src/autobahn/test/.... - Install & docs. Re-check
pip install -e .[dev,twisted,asyncio]and
cd docs && make htmlagainst the current extras ([all]/[dev]) and the
just docsrecipe.
Notes
- Pure documentation; no code/behaviour change.
- Keep
CONTRIBUTING.mdaligned withdocs/contributing.rstif both are shipped.
This analysis was produced with AI assistance (Claude Code) and requires human review before filing. Which I did.
Checklist
- I have searched existing issues to avoid duplicates
- I have provided a minimal reproducible example
- I have included version information
- I have included error messages/logs
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading CONTRIBUTING.md, then compare it with docs/contributing.rst, AI_POLICY.md, and .audit/AI_AUDIT_PROCESS.md. Verify the current just recipes, src-layout test path, install extras, and docs command before updating the guides. Done means both contributing guides document the issue-first, AI-disclosure, and branch rules and no longer reference stale commands or paths.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100