Document Test-Driven Workflow in CONTRIBUTING.md; Document PR audit file requirement

[oberstet]

Summary

The current CONTRIBUTING.md has a basic "Contributing Code" section but lacks detailed guidance on the test-driven bug fix / feature workflow that we expect contributors to follow. This workflow ensures PRs are convincing beyond any doubt and prevents regressions.

Problem

Contributors (especially new ones) often submit PRs that:

• Don't include tests proving the bug exists
• Don't demonstrate the fix actually works
• Don't provide evidence from both local runs AND CI

This makes review harder and less certain.

Proposed Documentation

Add a new section "Bug Fix Workflow" to CONTRIBUTING.md documenting the expected process:

Bug Fix Workflow (Test-Driven)

When fixing a bug, follow this workflow to create a convincing, reviewable PR:

1. File Issue & Discuss

• File a GitHub issue describing the bug
• Discuss and gather agreement: "yes, current behavior is wrong"
• Reference any related issues or user reports

2. Create PR with Failing Test

• Create a feature branch
• Write a test that demonstrates the bug (test should FAIL)
• Include any audit/fixture files needed
• Push the PR

3. Prove the Bug Exists

• Run tests locally → verify they FAIL
• Let GitHub Actions run → verify CI FAILS
• Leave a PR comment with:
  • Your local test output showing failure
  • Link to the failing CI workflow run

4. Implement the Fix

• Fix the bug
• Push the fix to the same PR

5. Prove the Fix Works

• Run tests locally → verify they PASS
• Let GitHub Actions run → verify CI PASSES
• Leave a PR comment with:
  • Your local test output showing success
  • Link to the passing CI workflow run

6. Request Review

• Comment: "Ready for review & merge!"
• Ping maintainers if needed

Why This Workflow?

This leaves maintainers with a completely convincing PR because:

• There is a behavior considered incorrect (bug)
• The test proves the current implementation is behaving incorrectly
• The fix proves the new implementation does fix it
• The test coverage ensures we won't regress later

Example PR Comments

After step 3 (proving bug exists):

## Bug Confirmed

Local test run:
​```
$ just test
...
FAILED test_foo.py::test_bar - AssertionError: expected X, got Y
​```

CI also fails: https://github.com/crossbario/crossbar/actions/runs/12345

After step 5 (proving fix works):

## Fix Verified

Local test run:
​```
$ just test
...
PASSED test_foo.py::test_bar
​```

CI passes: https://github.com/crossbario/crossbar/actions/runs/12346

Ready for review & merge!

Scope

This documentation should be added to CONTRIBUTING.md in all Crossbar.io related Python repos: txaio, autobahn-python, zlmdb, cfxdb, wamp-xbr

Related

• Dropping session in flight on caller side kills the session on callees side #2133 (discussion where this workflow was clarified)

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

[oberstet]

Part 2: Document PR Audit File Requirement

In addition to the test-driven workflow, we should document the audit file requirement for PRs.

Background

All repos in the WAMP ecosystem use a shared .ai/ submodule (from wamp-ai) that provides:

• AI policy and guidelines (AI_POLICY.md, CLAUDE.md)
• Git hooks enforcing AI disclosure
• Audit file generator for PRs

The .audit/ Directory

Each PR - whether it involved AI assistance or not - must include an audit file in .audit/:

.audit/
├── oberstet_modernization-phase-12.md
├── oberstet_modernization-phase-13.md
├── oberstet_modernization-phase-14.md
└── oberstet_modernization-take1.md

Naming convention: <github-user>_<sanitized-branch-name>.md

Audit File Contents

- [ ] I did **not** use any AI-assistance tools to help create this pull request.
- [x] I **did** use AI-assistance tools to *help* create this pull request.
- [x] I have read, understood and followed the project's AI_POLICY.md when creating code, documentation etc. for this pull request.

Submitted by: @oberstet
Date: 2025-12-05
Related issue(s): #2144
Branch: oberstet:modernization-phase-1.4

Generating Audit Files

Contributors use the generate-audit-file recipe from the .ai/ submodule:

# From the .ai/ directory in the repo
cd .ai
just generate-audit-file

This will:

1. Auto-detect branch name and GitHub username
2. Create .audit/<user>_<branch>.md from template
3. Pre-fill date and branch info
4. Prompt you to update the issue reference

Documentation to Add

Add a section "AI Assistance Disclosure" to CONTRIBUTING.md:

## AI Assistance Disclosure

If you used AI assistance (Claude, ChatGPT, Copilot, etc.) when creating your PR:

1. **Generate an audit file:**
   ```bash
   cd .ai
   just generate-audit-file

2. Edit the generated file in .audit/:

   • Update Related issue(s): with your issue number
   • Adjust checkboxes if you did NOT use AI assistance

3. Commit the audit file with your PR

This ensures transparency about AI-assisted contributions per our AI_POLICY.md, eg https://github.com/wamp-proto/wamp-ai/blob/d1647dc94b19a3c21c55ae8cbe28b214b0ed1a94/AI_POLICY.md

[oberstet]

this is a showcase example of the workflow:

• Issue => Dropping session in flight on caller side kills the session on callees side #2133
• PR => Test/caller disconnect callee crash #2153