4.3 KiB
Developing ReleaseKit
ReleaseKit contains a Go module with the documented root releasekit facade,
adopted policies, and design documents. See the README for
orientation.
Read the agent policy and inspect the worktree before editing. Preserve unrelated changes and follow explicit instructions about commits. The architecture policy governs development boundaries; ADR 0001 records the facade decision. The documentation policy owns the documentation topic map.
ADR 0002 records the priorities and non-goals behind ReleaseKit's standard, minimal API for routine releases.
Policy Reading Guide
| Policy | Read before… |
|---|---|
| Policy set provenance | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| Agents | Recommending, planning, or implementing repository changes. |
| Architecture | Planning or changing library or executable code or its structure. |
| Testing | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| Documentation | Writing, revising, or reorganizing documentation. |
| OSS | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| Release | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
- Read applicable policies before making decisions they govern; multiple policies may apply.
- Select policies using the task triggers above. Follow cross-references to relevant sections when needed to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere affected by the revision.
Validation
Run the offline Go test suite from the repository root with:
go test ./...
Run the compiled public API and dependency-boundary checks from the repository root with:
go run ./internal/apicheck
See the candidate check guide, source publication guide, build consumer guide, and internal package inventory for implemented behavior and capability ownership.
For prose changes, review the diff and check local links, fragment destinations, provenance, template residue, and consistency with current repository contents. Check prose whitespace with:
git diff --check -- '*.md' COPYRIGHT
git diff --cached --check -- '*.md' COPYRIGHT
Verbatim license texts retain their supplied formatting. When changing those texts, compare their bytes with the selected upstream source.
Run the source publication command from the candidate repository root with
./scripts/release VERSION. It uses the local Go toolchain and committed
releasekit.json profile; prepare module dependencies before offline candidate
validation. The maintainer release procedure owns preparation,
publication, and recovery. Hosted note-page delivery is a separate prepared
workflow and does not change the successful-tag-push completion point. ReleaseKit
does not declare binary deliverables.
Testing synthetic modules
Tests that serve synthetic module versions through local proxies should pass a
test-owned temporary GOMODCACHE to every Go subprocess that consumes those
versions. Scope fixture-specific proxy and checksum settings to those processes.
This applies the testing policy's isolation requirements
to module downloads and keeps fixture metadata out of developer and CI caches.
Distinct fixture version numbers still occupy the real module's cache namespace. Use temporary caches even when the selected versions have never been published. Verify isolation at the shared fixture boundary; ordinary builds can continue to use their prepared dependency cache. Consumer recovery guidance lives in the module checksum investigation guide.