# Developing ReleaseKit

ReleaseKit contains a Go module with the documented root `releasekit` facade,
adopted policies, and design documents. See the [README](../README.md) for
orientation.

Read the [agent policy](policy/agents.md) and inspect the worktree before editing.
Preserve unrelated changes and follow explicit instructions about commits.
The [architecture policy](policy/architecture.md) governs development boundaries;
[ADR 0001](adr/0001-public-facade.md) records the facade decision. The
[documentation policy](policy/documentation.md#canonical-ownership) owns the
documentation topic map.

[ADR 0002](adr/0002-routine-releases.md) records the priorities and non-goals
behind ReleaseKit's standard, minimal API for routine releases.

## Policy Reading Guide

| Policy | Read before… |
| --- | --- |
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing library or executable code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | 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:

```sh
go test ./...
```

Run the compiled public API and dependency-boundary checks from the repository
root with:

```sh
go run ./internal/apicheck
```

See the [candidate check guide](consumers/check.md), [source publication guide](consumers/publish.md),
[build consumer guide](consumers/build.md),
and [internal package inventory](internal/overview.md) 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:

```sh
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](release.md) 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](policy/testing.md#test-execution-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](consumers/delivery.md#investigating-module-checksum-mismatches).