crossbario / crossbario/autobahn-python

[CHORE] Refresh CONTRIBUTING.md: document issue-first + AI-disclosure (.audit) requirements; fix stale tox/paths

Open
#1,889 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug CI-CD docs
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
    and AI_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 py312 section with the
    current just recipes (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 html against the current extras ([all]/[dev]) and the
    just docs recipe.

Notes

  • Pure documentation; no code/behaviour change.
  • Keep CONTRIBUTING.md aligned with docs/contributing.rst if 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.