179 lines
10 KiB
Markdown
179 lines
10 KiB
Markdown
# Adopt the policy framework
|
|
|
|
Status: Policy adoption complete. Release publication implementation is pending.
|
|
|
|
Date: 2026-10-05
|
|
|
|
## Purpose and scope
|
|
|
|
Standard Repository Policies are adopted into ReleaseKit as locally maintained
|
|
rules for an opinionated Go library and its proposed release executable. The
|
|
adoption preserves the project's existing licensing choice, supports deliberate
|
|
standardization of release behavior, and keeps 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](releasekit.md).
|
|
|
|
## 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](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
|
|
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](../../../ConfigKit/docs/policy/architecture.md),
|
|
[PromptKit's architecture policy](../../../promptkit/docs/policy/architecture.md),
|
|
and their documentation, testing, and attribution policies. Use these as examples
|
|
of adaptation rather than copying their product-specific requirements.
|
|
|
|
## Policy adaptations
|
|
|
|
All seven policies are adopted 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. |
|
|
|
|
## Adopted architectural constraints
|
|
|
|
The [architecture policy](../policy/architecture.md) owns the adopted boundaries,
|
|
including [ADR 0001](../adr/0001-public-facade.md) and the runtime version
|
|
constraints. The following summarizes those rules for this adoption record.
|
|
|
|
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
|
|
|
|
- [x] Copy the seven policies from the selected baseline.
|
|
- [x] 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.
|
|
- [x] Customize the policies for ReleaseKit and remove their `Base Policy
|
|
Template` sections.
|
|
- [x] Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving the
|
|
existing knowledge-graph discovery instructions.
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] Update README with accurate current status and navigation.
|
|
- [x] Define ownership for GoDoc, consumer guidance, architecture constraints,
|
|
internal implementation, release procedures, ADRs, and unfinished work.
|
|
- [x] Reserve consumer, CLI, configuration, integration, and internal ownership
|
|
in the documentation policy. Their documents await corresponding implementation;
|
|
no empty owners or speculative command references were created.
|
|
|
|
### 3. Complete notices and attribution
|
|
|
|
- [x] Add root `COPYRIGHT` using the upstream library example and verified project
|
|
details. The grant is `LGPL-3.0-or-later`, consistent with the existing library
|
|
licensing choice and the two library examples.
|
|
- [x] Restore the complete, verbatim LGPLv3 and incorporated GPLv3 texts in
|
|
`LICENSE`; the original contained reformatted text and a customized appendix.
|
|
Keep project-specific grant statements in `COPYRIGHT`.
|
|
- [x] Add `docs/oss/attribution.md` with the supplied policy attribution entry,
|
|
describing the actual adapted policies, agent orientation, and reading guide.
|
|
- [x] 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`.
|
|
- [x] 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
|
|
|
|
- [x] Adopt the general versioning, compatibility, integrity, immutability, and
|
|
successful-tag-push completion rules.
|
|
- [x] Select source only as ReleaseKit's initial deliverable in the release
|
|
policy. Supporting downstream cross-builds does not declare ReleaseKit binaries.
|
|
- [ ] Add `docs/release.md` alongside the first working publication command,
|
|
documenting real prerequisites, authoritative remote, branch, validation,
|
|
publication, and failure recovery.
|
|
- [x] Account for first-release bootstrap: the initial publication command must
|
|
run from the captured candidate source with dependencies prepared separately.
|
|
The first release uses that source execution path before a released ReleaseKit
|
|
tool exists. Document and verify the actual command when it is implemented.
|
|
- [ ] Add executable delivery declarations and target checks when corresponding
|
|
deliverables exist. Keep source completion and asynchronous delivery status
|
|
separate. This task is deferred unless executable deliverables are selected.
|
|
|
|
The publication command, its automated guards and offline candidate validation,
|
|
and the executable maintainer runbook remain product implementation work. This
|
|
adoption does not claim an available release command or perform publication.
|
|
|
|
## 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.
|
|
|
|
## Adoption result
|
|
|
|
The seven policies, root agent orientation, developer reading guide, documentation
|
|
ownership, project grant, attribution, and license texts are in place. The product
|
|
proposal lives at `docs/roadmap/releasekit.md`; `ideas.md` remains a navigation
|
|
pointer. Future capabilities retain their proposed status, and facade
|
|
implementation remains pending in the product roadmap.
|
|
|
|
Verification covers local file and fragment links, per-policy source revision and
|
|
base version, removed template adoption sections, attribution scope and pinned
|
|
notice destinations, verbatim license bytes, and prose whitespace. The preserved
|
|
ADR decision and relocated proposal are checked against their pre-adoption source.
|
|
Release automation and its runbook remain pending under stage 4 as permitted by
|
|
this roadmap's completion criteria.
|