109 lines
6.8 KiB
Markdown
109 lines
6.8 KiB
Markdown
# Standard Policy Documentation Alignment
|
|
|
|
Status: accepted target; execution is defined in the [implementation plan](implementation.md).
|
|
|
|
## Intent and baseline
|
|
|
|
Align ConfigKit's adopted documentation with Standard Repository Policies while
|
|
preserving substantive local decisions. Prefer upstream wording verbatim wherever
|
|
differences are editorial; do not maintain a parallel local paraphrase of shared
|
|
rules. Customization must serve a locally significant requirement.
|
|
|
|
Local baseline: `0adb94f59e44827908eff401d4381a398fe17107` (v0.4.1).
|
|
The selected upstream revision is
|
|
`d84a38ebab26f048cafbe59a2246700c35d29843`. Its
|
|
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
|
|
owns the standard adoption procedure. This roadmap covers the adopted policy set,
|
|
not just `docs/policy/documentation.md`.
|
|
|
|
ConfigKit currently has six policies, no `meta.md`, and no per-document
|
|
`Upstream Source` links. Its contributor guide routes tasks to documents but lacks
|
|
the upstream selective-reading guidance. Licensing documentation covers the
|
|
project and YAML dependency but not copied policy material. The release policy
|
|
has intentionally retained its established workflow.
|
|
|
|
Introduce accurate provenance going forward. Do not reconstruct old adoption
|
|
baselines or add historical-uncertainty narratives.
|
|
|
|
## Target policy set
|
|
|
|
Remove upstream template instructions after adoption. Retain shared substantive
|
|
wording unchanged except for necessary local adaptation and working references.
|
|
|
|
| Document | Target |
|
|
| --- | --- |
|
|
| `docs/policy/meta.md` | Adopt upstream v1.0: local authority, upstream origin, discovery links, and policy provenance. |
|
|
| `docs/policy/agents.md` | Adopt v1.3 wording, retaining local explanations of correctness constraints, protection of established contracts, and the rule that repeated agent-authored assertions are not evidence of approval. No change to standing commit authority. |
|
|
| `docs/policy/architecture.md` | Use v1.3 as the customized template while preserving the opinionated library model, root-owned facade, dependency direction, existing invariants, and explicit avoidance of an imposed hexagonal framework. No code restructuring or new threat guarantees. |
|
|
| `docs/policy/testing.md` | Adopt v1.3 shared wording. Retain ConfigKit-specific priorities and test ownership. Tests protect selected contracts; examples must not imply new rejection rules or mandatory inventories of techniques. |
|
|
| `docs/policy/documentation.md` | Adopt v1.11 wording with a library-specific ownership table, including policy provenance. Omit inapplicable interfaces and empty placeholder documents. |
|
|
| `docs/policy/oss.md` | Adopt v1.8 wording with necessary ConfigKit applicability and reference adjustments. Preserve the selected project grant and house interpretation of upstream notice links. |
|
|
| `docs/policy/release.md` | Adopt compatible wording and accurate source metadata, preserving current operational requirements as explicit local adaptations until the separate release-workflow task lands. Do not describe the future publication command as implemented. |
|
|
|
|
Each adopted document identifies its actual upstream template version, local
|
|
update date, and full commit-specific `Upstream Source` URL. A deliberate adoption
|
|
from the selected revision establishes the new baseline even where substantial
|
|
project-specific content remains. Metadata must not imply adoption of upstream
|
|
requirements deliberately replaced by local rules.
|
|
|
|
## Orientation and upstream navigation
|
|
|
|
Adapt upstream `agents/AGENTS.md` into the root orientation file. Keep the required
|
|
agent-policy reading rule and route other reading through `docs/development.md`.
|
|
The developer guide owns task triggers for all seven policies, including policy
|
|
reviews through `meta.md`. Readers select applicable policies, reuse unchanged
|
|
material already in context, follow relevant cross-references, and expand reading
|
|
when scope changes. Reading the entire suite is not the default.
|
|
|
|
Use live upstream project and adoption-guide URLs for discovery. Pin adopted-source
|
|
and licensing-example URLs to full commits. Keep the upstream README, root agent
|
|
instructions, contributor guide, adoption guide, and example collection upstream;
|
|
do not copy them into ConfigKit. Root orientation derives from the upstream
|
|
`agents/AGENTS.md` template, not its root AGENTS.md.
|
|
|
|
## Attribution and licensing target
|
|
|
|
Use the upstream canonical Standard Repository Policies entry in
|
|
`docs/oss/attribution.md`, identifying the actual adapted material and linking its
|
|
source, COPYRIGHT, and LICENSE at the selected commit. Include adapted orientation
|
|
material where applicable. Preserve notices and modification identification
|
|
without adding research or compliance narratives.
|
|
|
|
Copy the applicable CC-BY-SA-4.0 text verbatim into `docs/oss/licenses/` and identify
|
|
the separately licensed policy-document scope in root COPYRIGHT. ConfigKit code
|
|
retains LGPL-3.0-or-later; root LICENSE retains the project license texts. Original
|
|
upstream example formatting is CC0 and does not itself require an attribution
|
|
entry or copying the example collection.
|
|
|
|
Normalize the existing YAML entry to the current House Format: the prescribed
|
|
document title, factual component identification, actual notice filenames,
|
|
punctuation, and Source link. Remove editorial explanations while retaining
|
|
upstream notices, copyright statements, license expression, and exact source
|
|
revision. Keep MIT and Apache texts unchanged. Do not restore the author-owned
|
|
adaptation section that the maintainer expressly removed.
|
|
|
|
## Change surface and boundaries
|
|
|
|
Affected files are the policy documents, root `AGENTS.md`, `docs/development.md`,
|
|
COPYRIGHT, `docs/oss/attribution.md`, and the new CC license text. Repair affected
|
|
local links and any misleading licensing summaries. Shared rules belong in their
|
|
owning policies, not duplicated in the orientation guide or attribution entries.
|
|
|
|
The [release-workflow roadmap](release.md) owns publication automation and gate
|
|
selection. This work may align wording and references but does not alter release
|
|
scripts, existing gates, supported platforms, publication completion, or library
|
|
behavior. Coordinate edits to the release policy rather than maintaining two
|
|
competing definitions. Published tags and historical release notes remain intact.
|
|
|
|
## Completion criteria
|
|
|
|
The policy set uses upstream language except for justified local substance,
|
|
contains accurate forward-looking adoption metadata, and has working orientation
|
|
and attribution links. Existing local contracts and explicit maintainer decisions
|
|
remain intact. Documentation-link and whitespace checks, license-text comparisons,
|
|
and ordinary content review provide proportionate validation. No synchronization
|
|
service, scanner, legal sign-off, or new release gate is introduced.
|
|
|
|
This roadmap defines the desired end state and local policy choices. It
|
|
authorizes neither publication nor a release.
|