Chapter 06

Testing and release

A change is ready for users when tests, documentation, release notes, and runtime validation all still match the shipped behavior—not only when the code compiles locally.

Testing rules in this repository

Every code change must add or update test coverage.
Source code stays in src/; tests stay in test/.
Use unit tests for local behavior and integration tests for runtime-visible behavior.
For frontend or docs-site changes, verify the rendered result, not only the source text.

What readers notice

If a docs-site change has no test asserting its entry points and navigation, readers can hit broken links or missing pages—so treat navigation coverage as part of the change.

Recommended test stack

Unit tests

Validate local parsing, config compilation, policy logic, and other isolated behavior.

Integration tests

Validate runtime-visible behavior such as approvals, persistence, exports, transports, and recovery.

Docs-site tests

Validate navigation, entry points, and key wording for the shipped static documentation surface.

Real-environment checks

Use real providers or deployment paths when behavior depends on external systems.

Integration and real-environment validation

The repository guidance explicitly calls for integration testing against a real environment when the change requires it. Local confidence is not enough if the runtime contract depends on provider behavior, external protocols, or GitHub Actions release flow.

npm test
./node_modules/.bin/vitest run test/docs/developer-docs-site.test.ts
./node_modules/.bin/vitest run test/docs/docs-site.test.ts

Keep documentation aligned with shipped behavior

Every feature change should include an explicit documentation pass. At minimum, check whether the behavior change requires updates to README.md, README.zh.md, docs/index.html, affected topical docs under docs/, and RELEASE_NOTES.md.

Always review

README.md, README.zh.md, docs homepage, topical docs, and release notes.

Why it matters

Behavior that ships without matching docs leaves users following outdated guidance—effectively a second defect alongside the code change.

Release flow

Triage and confirm the issue or defect.
Implement the smallest product-owned fix.
Add unit and integration coverage.
Update documentation and release notes in the same change.
Push, monitor GitHub Actions, and keep fixing until the pipeline is green.
If the change resolves an issue, close the issue after the release is confirmed.

GitHub Actions posture

Pushing to master is not the end of the task. The release is only complete when the relevant workflows for the new head commit have finished successfully.

Ship checklist

Code

The implementation matches the product boundary and runtime contract.

Tests

Unit and integration coverage prove the runtime-visible behavior.

Docs

README, docs site, topical docs, and release notes are aligned with the shipped behavior.

Release

CI is green, release artifacts are healthy, and the linked issue can be closed.

Pre-release verification checklist

The code matches the product boundary.
The changed behavior has focused tests.
Docs and release notes reflect the shipped behavior.
GitHub Actions for the new master head commit are green.
Any linked issue can be closed with a clear explanation of what shipped.