Issue & PR Etiquette
The repo does not need elaborate process. It does need legible process.Issues
Good issues are specific enough that another contributor can act on them without guessing the problem statement. Include:- what behavior is wrong or missing
- where it shows up
- whether it is current behavior or target-state documentation drift
- reproduction steps when relevant
- screenshots or payload samples when they materially help
- vague “improve X” requests
- combining several unrelated bugs in one issue
- reporting target-state ideas as if they are regressions
Pull requests
Good pull requests make review cheap. Include:- a short summary of what changed
- why the change is needed
- tests added or affected
- docs updated
- known gaps or follow-up work
Review etiquette
- keep review comments concrete and technical
- challenge assumptions, not people
- point out behavior drift and missing docs early
- prefer exact file/path references over general statements
- if a change expands scope mid-flight, split it
Maintainer expectations
- close the loop on review feedback
- mark follow-up work explicitly instead of hiding it
- do not merge behavior-changing work with red checks
- keep docs aligned with the current repo state