ReleaseKit/docs/roadmap/policy.md

Adopt the policy framework

Status: Proposed; adoption has not started.

Date: 2026-10-05

Purpose and scope

Adopt Standard Repository Policies into ReleaseKit as locally maintained rules for an opinionated Go library and its proposed release executable. The adoption should preserve the project's existing licensing choice, support deliberate standardization of release behavior, and keep documentation accurate about what has been implemented.

This roadmap covers policy adoption, contributor navigation, documentation ownership, licensing notices, and the preparation of ReleaseKit's own release procedure. Product implementation and consumer migrations belong to the separate ReleaseKit proposal.

Upstream baseline and references

Use upstream commit d84a38ebab26f048cafbe59a2246700c35d29843. The local ../policy checkout and upstream main matched that revision during the review. PromptKit and ConfigKit adopted the same baseline.

Follow the adoption guide at the selected revision. Copy applicable policies locally and customize them. Retain each file's exact upstream provenance; later upstream changes become local rules through deliberate review and adoption. Git history is sufficient to record this process.

Useful library adaptations include ConfigKit's architecture policy, PromptKit's architecture policy, and their documentation, testing, and attribution policies. Use these as examples of adaptation rather than copying their product-specific requirements.

Policy adaptations

Adopt all seven policies under docs/policy/:

Policy	Base version	ReleaseKit adaptation
meta.md	1.0	Retain local authority, per-document adoption provenance, and upstream update navigation.
agents.md	1.3	Retain proportionate implementation and local commit practices. Add the libraries' clarification that implementation, tests, and agent-authored plans do not independently establish new contracts.
architecture.md	1.3	Define the library, proposed executable, consumer responsibilities, external effects, and dependency boundaries.
testing.md	1.3	Retain behavioral, deterministic, offline testing. Prioritize publication integrity, ambiguous outcomes, partial delivery, cross-builds, and version injection as those features are implemented.
documentation.md	1.11	Assign exact exported Go contracts to declarations and GoDoc, workflows to consumer guides, and proposals to roadmap documents. Add CLI and integration owners when those interfaces exist.
oss.md	1.8	Preserve the library licensing choice, apply the attribution format, and identify separately licensed copied policy material.
release.md	1.4	Govern releases of ReleaseKit itself, with explicit deliverables and justified checks. Distinguish its maintainer procedure from the release standard offered to consumers.

Proposed architectural constraints

The public facade decision is accepted in ADR 0001. Policy adoption will incorporate that decision alongside the remaining proposed constraints below.

Evaluate ReleaseKit against both of ConfigKit's relevant success criteria: applications should delete substantial infrastructure, and consumers should adopt one consistent set of deliberately selected conventions.

• ReleaseKit owns the selected publication, version injection, build, and delivery conventions. Consumers supply product identity, main package, selected targets, and application-specific checks.
• Consumers use the root releasekit orchestration facade and the lightweight buildinfo runtime facade. Both packages own their public contracts and delegate through private state and explicit conversions to internal implementation. ReleaseKit builds and tests independently of the consuming repositories and does not depend on their private packages.
• Git, filesystem, Go toolchain, and Gitea effects have proportionate boundaries and occur through explicit operations. Package layout and abstractions should serve those boundaries without requiring an application framework.
• The library returns meaningful errors and publication outcomes. The executable handles command parsing, output, and exit codes.
• The buildinfo facade provides runtime version access through a lightweight dependency graph. ReleaseKit's builder and runtime implementation own version injection together.

Architecture policy may govern future development. Concrete package inventory, API semantics, and implemented behavior must be documented when they exist.

Adoption stages

1. Copy and tailor policies

• Copy the seven policies from the selected baseline.
• Preserve each Base Policy Version, set Last Updated to the actual adoption date, and add an Upstream Source link to that file at the full commit.
• Customize the policies for ReleaseKit and remove their Base Policy Template sections.
• Adapt upstream agents/AGENTS.md into root AGENTS.md, preserving the existing knowledge-graph discovery instructions.
• Create docs/development.md with contributor orientation and the selective policy reading guide. Route tasks to applicable policies instead of requiring the entire suite for every task.

2. Establish documentation ownership

• Move the substantive contents of ideas.md to docs/roadmap/releasekit.md, preserving the proposal, and retain ideas.md as a navigation pointer. Update this roadmap's proposal link in the same change.
• Update README with accurate current status and navigation.
• Define ownership for GoDoc, consumer guidance, architecture constraints, internal implementation, release procedures, ADRs, and unfinished work.
• Create consumer, CLI, configuration, integration, and internal documents when substantive implemented responsibilities justify them. Avoid empty owners and speculative command or API references.

3. Complete notices and attribution

• Add root COPYRIGHT using the upstream library example and verified project details. The recommended grant is LGPL-3.0-or-later, consistent with the two library examples; preserve any established author choice.
• Verify the existing LGPLv3 and incorporated GPLv3 texts in LICENSE are complete and faithful. Keep project-specific grant statements in COPYRIGHT.
• Add docs/oss/attribution.md with the supplied policy attribution entry, describing the actual adapted policies, agent orientation, and reading guide.
• Copy the CC-BY-SA 4.0 text to docs/oss/licenses/CC-BY-SA-4.0.txt and identify the copied material's separate licensing scope in COPYRIGHT.
• Add README links to the project grant and attribution document. Keep source and notice links pinned to the adopted commit and reference examples upstream.

The library's selected license remains the project grant. A future executable does not automatically acquire a different license merely because the upstream policy has separate defaults for applications and libraries.

4. Define ReleaseKit's own release path

• Adopt the general versioning, compatibility, integrity, immutability, and successful-tag-push completion rules.
• Select ReleaseKit's own deliverables explicitly. Supporting downstream cross-builds does not by itself require ReleaseKit to distribute binaries.
• Add docs/release.md alongside the first working publication command, documenting real prerequisites, authoritative remote, branch, validation, publication, and failure recovery.
• Account for the first-release bootstrap before a released ReleaseKit tool is available for its own publication.
• Add executable delivery declarations and target checks when corresponding deliverables exist. Keep source completion and asynchronous delivery status separate.

Validation and completion

Review provenance, attribution scope, faithful license texts, template residue, local links, whitespace, and consistency with implemented repository behavior. Documentation-only adoption should use those checks; executable commands and examples added later require appropriate execution checks.

Adoption is complete when the tailored policy set, contributor navigation, documentation ownership, and licensing notices are coherent and verified. The release-path stage may remain pending until publication is implemented; record that status without documenting an unavailable command as usable.

Do not inherit PromptKit's or ConfigKit's extra release gates automatically. Select additional checks only for identified ReleaseKit risks, recording their justification in the adopted policy. Upstream synchronization, recurring license approval, and CI polling are not additional adoption or release gates.