eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Document ReleaseKit proposal, policy roadmap, and facade architecture

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-05 14:26:42 +00:00
parent 3cbb3f3406
commit 4f914f10cf
3 changed files with 440 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/roadmap/policy.md Normal file
View File

@@ -0,0 +1,156 @@
# 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.