157 lines
8.8 KiB
Markdown
157 lines
8.8 KiB
Markdown
# 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](../../ideas.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
|
|
|
|
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](../adr/0001-public-facade.md). 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.
|