// How to approach code coverage in this project. Use when coverage CI fails, when writing tests for new code, when deciding whether to add // coverage-ignore, or when you need to make untestable code testable. Also use proactively when writing new code to ensure it will be coverable.
Changelog style guide for writing RELEASE.md files. Use when creating or reviewing RELEASE.md, writing changelog entries, or preparing a PR that needs a changelog.
Go concurrency patterns and pitfalls for this codebase. Use when writing or reviewing code that involves goroutines, channels, mutexes, shared state, subprocess management, or anything that runs concurrently. Also use proactively when writing new code — ask yourself: can this be called from multiple goroutines? Is this resource process-global?
Review your own changes before creating a pull request. Use this before running create-pr, or whenever you want to check that your changes are clean, correct, and well-tested. Trigger when: about to create a PR, finished a chunk of work, or asked to review changes.
| name | coverage |
| description | How to approach code coverage in this project. Use when coverage CI fails, when writing tests for new code, when deciding whether to add // coverage-ignore, or when you need to make untestable code testable. Also use proactively when writing new code to ensure it will be coverable. |
This project requires 100% line coverage for new code, with explicit coverage-ignore annotations only allowed under rare circumstances and with human permission.
This is implemented as a ratchet which counts the number of lines annotated as not requiring coverage. If the number of excluded lines exceeds the ratchet value, or if there are any uncovered lines without a // coverage-ignore annotation, the coverage check fails.
The coverage-ignore count in .github/coverage-ratchet.json tracks excluded lines and can only decrease. Just because previous work reduced the count does not mean you have implicit permission to add new uncovered lines. Think of the ratchet as immediately ratcheting down after any reduction — the slack is gone.
You may not add // coverage-ignore annotations without explicit human permission. If you think code is genuinely untestable, your first move should be to refactor it for testability, not to annotate it. See references/patterns.md for testability refactoring examples.
Tests should catch real bugs, not mirror the implementation.
When CI coverage fails:
references/patterns.md for information on how to do that.panic("hegel: unreachable: ...").just test locally to iterate faster than CI.For details on how the coverage script works and what it auto-excludes, see references/internals.md.