Align policy provenance and licensing documentation
This commit is contained in:
@@ -1,140 +1,177 @@
|
||||
# Documentation Policy
|
||||
|
||||
**Base Policy Version:** 1.1
|
||||
**Base Policy Version:** 1.11
|
||||
|
||||
**Last Updated:** 2026-09-26
|
||||
**Last Updated**: 2026-09-28
|
||||
|
||||
Licensing ownership incorporates the upstream documentation policy v1.5;
|
||||
unrelated policy revisions remain outside this adoption.
|
||||
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
|
||||
|
||||
## Purpose
|
||||
|
||||
Assign each documentation topic one canonical owner so ConfigKit's documentation
|
||||
remains accurate and useful to consumers, maintainers, and implementation agents.
|
||||
This policy assigns each documentation topic to one canonical owner. Its goal is
|
||||
to keep ConfigKit's documentation accurate, concise, discoverable, and resistant
|
||||
to drift for consumers, maintainers, developers, and coding agents.
|
||||
|
||||
## Core rules
|
||||
## Core Rules
|
||||
|
||||
### One canonical owner
|
||||
### One Canonical Owner
|
||||
|
||||
Each authoritative fact belongs in one owning document or Go declaration's
|
||||
reference documentation. Other documents may summarize and link to that owner;
|
||||
they must not maintain competing definitions of commands, API contracts, YAML
|
||||
semantics, defaults, paths, diagnostics, or compatibility guarantees.
|
||||
Each authoritative fact belongs in one document. A non-owning document may give
|
||||
a short, stable summary for orientation, but it must link to the canonical owner
|
||||
for volatile details.
|
||||
|
||||
### Policies, current behavior, and future work
|
||||
Volatile details include commands, flags, configuration fields and defaults,
|
||||
module keys, schemas, file names, paths, status codes, retry behavior, and
|
||||
runtime guarantees. If readers could reasonably treat a statement as a
|
||||
contract, maintain it only in the owning document.
|
||||
|
||||
- Policies state currently binding contributor rules, including constraints on
|
||||
future implementation. They do not imply that features already exist.
|
||||
- Current API/configuration contracts, consumer guidance, and component
|
||||
documentation describe implemented behavior only, including partial boundaries.
|
||||
- ADRs record accepted decisions and rationale. Acceptance is not evidence of
|
||||
implementation; execution status belongs in roadmaps.
|
||||
- Roadmaps own unimplemented targets, deferred work, and execution status.
|
||||
### Current And Future Behavior
|
||||
|
||||
Future implementation plans own their task order, acceptance gates, and progress;
|
||||
`docs/roadmap/deferred.md` owns deliberate exclusions, not execution instructions.
|
||||
As behavior lands, move its normative definition into the current contract and
|
||||
replace the roadmap definition with a link. Retire completed roadmap material
|
||||
as part of release preparation; ADRs preserve significant decision history.
|
||||
Outside `docs/roadmap/`, documentation describes implemented behavior only.
|
||||
Partial features may be described only to their implemented boundary.
|
||||
|
||||
### Audience and examples
|
||||
Architectural constraints may govern future changes. Describe current structure
|
||||
from implemented behavior.
|
||||
|
||||
Consumer documentation explains how to use the library and what consumers own.
|
||||
Internal documents explain mechanisms and dependencies. Keep implementation
|
||||
mechanics out of consumer guidance unless they affect a meaningful choice.
|
||||
ADRs may record an accepted architectural decision before implementation. The
|
||||
roadmap owns implementation status and sequencing until the decision is
|
||||
implemented. Current architecture, user, operator, integration, and internal
|
||||
documentation are updated when the behavior lands.
|
||||
|
||||
Complete copyable artifacts belong in `examples/`; Go API examples may live in
|
||||
executable Go example tests beside the relevant package. Prose should use the
|
||||
smallest useful excerpt and link to the maintained artifact. Examples must be
|
||||
secret-free and checked against implemented behavior. Clearly label illustrative
|
||||
future syntax in roadmaps; do not present it as a runnable current example.
|
||||
`docs/roadmap/deferred.md` owns deliberate exclusions; task-specific plans
|
||||
own execution order and progress. Completed plans retire during release
|
||||
preparation.
|
||||
|
||||
### Security and privacy
|
||||
### Audience And Detail
|
||||
|
||||
Do not include real credentials, private keys, environment dumps, sensitive input,
|
||||
or private infrastructure details unless intentionally public. Document secret
|
||||
handling, not secret values.
|
||||
Write for the document's stated audience and include only the detail needed for
|
||||
its owned topic. Keep user and operator docs focused on using and operating the
|
||||
application. Developer docs should link to user-facing and external contracts
|
||||
for their definitions.
|
||||
|
||||
## Canonical ownership
|
||||
### Examples
|
||||
|
||||
| Topic | Owner | Boundary |
|
||||
| --- | --- | --- |
|
||||
| Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example |
|
||||
| Contributor entry point | `docs/development.md` | Reading guide and actual baseline validation commands |
|
||||
| Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries |
|
||||
| Agent rules | `docs/policy/agents.md` | Implementation discipline, proportionality, rules against inventing contracts, and local commit authorization; not application contracts or architecture |
|
||||
| Documentation rules | `docs/policy/documentation.md` | Ownership and document lifecycle |
|
||||
| Testing rules | `docs/policy/testing.md` | Risk-based sufficiency, test boundaries, and maintenance principles |
|
||||
| Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions |
|
||||
| Licensing and attribution rules | `docs/policy/oss.md` | Project licensing conventions, attribution format, notice links, discoverability, and maintenance |
|
||||
| Project grant | `COPYRIGHT` | Project identity, holders and years, SPDX expression, grant, disclaimer, and third-party statement |
|
||||
| Project license texts | `LICENSE` | Complete selected license and incorporated companion text |
|
||||
| Upstream attribution | `docs/oss/attribution.md` | Component names, copyright statements, license identification, and source/license/notice links |
|
||||
| Standard dependency license texts | `docs/oss/licenses/` | Complete verbatim texts, not project-specific upstream notices |
|
||||
| Release procedure | `docs/release.md` | Exact maintainer commands, prerequisites, supported targets, and verification |
|
||||
| Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle API behavior |
|
||||
| YAML and resolution semantics | `docs/config.md` | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
|
||||
| Consumer walkthroughs | `docs/consumers/`, when useful | Task-oriented usage and consumer responsibilities, not duplicate API reference |
|
||||
| Component inventory | `docs/internal/overview.md` | Implemented components and links to their owners |
|
||||
| Component mechanics | Other `docs/internal/` files, when needed | Detailed implementation behavior and change recipes |
|
||||
| Architectural decisions | `docs/adr/` | Context, decisions, alternatives, consequences, and supersession history |
|
||||
| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and the conditions for reconsidering them |
|
||||
| Future implementation plans | Task-specific files under `docs/roadmap/` | Unfinished work, task order, acceptance gates, and progress; completed plans retire to Git history |
|
||||
| Historical release notes | `docs/releases/` | Version-specific historical summaries required by release policy |
|
||||
| Complete examples | `examples/` and executable Go examples | Maintained artifacts; prose links instead of duplicating full examples |
|
||||
Complete copyable files belong in `examples/`. Documentation may use the
|
||||
smallest illustrative snippet needed to explain its owned topic, but should link
|
||||
to maintained examples for complete copyable files.
|
||||
|
||||
A listed owner is not a requirement to create an empty file before it has useful
|
||||
content. Create API, consumer, example, and component documents when the corresponding behavior
|
||||
exists and there is useful content to own. Link only to existing files; use plain
|
||||
code paths for planned files. Unvalidated candidate and publication work has the
|
||||
explicit temporary exception recorded in the release policy.
|
||||
Executable Go API examples may live beside the relevant package.
|
||||
|
||||
ConfigKit has no owned HTTP service, application CLI, or runtime operations
|
||||
interface. Do not create those reference documents for consuming applications.
|
||||
Examples must be valid, secret-free, and tested where practical. Commands and
|
||||
configuration used in documentation should match the application.
|
||||
|
||||
## Boundary rules
|
||||
### Security And Privacy
|
||||
|
||||
The [OSS policy](oss.md) owns licensing and attribution conventions. COPYRIGHT
|
||||
owns the project grant, LICENSE owns its complete texts, and attribution entries
|
||||
own component-specific information. README and new release documents provide
|
||||
navigation; the release procedure owns concrete release URLs and publication
|
||||
mechanics. Do not duplicate notice lists in those documents.
|
||||
Documentation and examples must not contain real credentials, private keys,
|
||||
private environment dumps, sensitive source material, or private infrastructure
|
||||
details unless intentionally public. Document secret-handling mechanisms, not
|
||||
secret values.
|
||||
|
||||
Architecture owns governing constraints; ADRs explain why; contracts describe
|
||||
implemented semantics; internal documentation explains how. A roadmap may link
|
||||
to all of them but must not become a second current reference.
|
||||
## Canonical Ownership
|
||||
|
||||
Release policy owns guarantees; the release procedure owns commands. A release
|
||||
note cannot redefine a compatibility contract or replace a current-documentation
|
||||
update. The note at an immutable tag is that release's historical record.
|
||||
| Topic | Canonical owner | Owned content | Content owned elsewhere |
|
||||
| --- | --- | --- | --- |
|
||||
| Product orientation and minimal example | `README.md` | Purpose, current status, shortest useful Go example, and navigation, including licensing and attribution. | Full Go API and configuration contracts, release procedure, and implementation detail. |
|
||||
| Contributor entry point | `docs/development.md` | Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
|
||||
| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
|
||||
| Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Policy-set origin, local authority, adoption baselines, and upstream adoption and update links. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. |
|
||||
| Agent policy | `docs/policy/agents.md` | Proportionate, idiomatic implementation; rules against inventing requirements, restrictions, guarantees, or policy. | Application contracts, architecture, testing policy, and contributor procedures. |
|
||||
| Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
|
||||
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
|
||||
| Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. |
|
||||
| Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
|
||||
| Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, code grant, separately licensed document scope, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. |
|
||||
| Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. |
|
||||
| Upstream component attribution | `docs/oss/attribution.md` | House Format entries for dependencies and adapted documents: identity, material scope, copyright, license, notices, and source links. | General policy, exception reasoning, and complete standard license texts. |
|
||||
| Standard license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries, including copied documentation. | Project-specific upstream notices, attribution prose, and policy interpretation. |
|
||||
| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
|
||||
| Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle behavior. | Shared YAML semantics and complete examples. |
|
||||
| Configuration contract | `docs/config.md` | YAML syntax, composition, precedence, schema, defaults, resolution, validation, secrets, and explanation semantics. | Go symbol contracts, complete examples, and implementation detail. |
|
||||
| Consumer guidance for the public Go API | `docs/consumers/` | Task-oriented public Go API usage, minimal examples, and consumer responsibilities. | Go symbol contracts, configuration semantics, and internal implementation detail. |
|
||||
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
|
||||
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
|
||||
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
|
||||
| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and conditions for reconsideration. | Task execution and current behavior. |
|
||||
| Future implementation plans | Task-specific files under `docs/roadmap/` | Unfinished work, sequencing, acceptance, and progress; completed plans retire during release preparation. | Implemented behavior and ADR rationale. |
|
||||
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
|
||||
| Complete examples | `examples/` and executable Go examples | Maintained copyable artifacts and Go API examples. | Configuration reference, symbol contracts, and prose explanation. |
|
||||
|
||||
This policy owns what documentation may disclose. Architecture owns security
|
||||
invariants. Current configuration and Go API contracts own secret-classification
|
||||
and rendering behavior when implemented; internal docs own their mechanisms.
|
||||
Create supporting documents for existing interfaces and responsibilities when
|
||||
substantive content is available.
|
||||
|
||||
## Architectural decision records
|
||||
Do not create empty owners. Unvalidated candidate and publication work has
|
||||
the temporary exception recorded in the release policy.
|
||||
|
||||
Use sequential filenames, such as `0001-separate-composition-and-overlay.md`,
|
||||
and the lightweight Nygard structure: title, status, date, context, decision,
|
||||
alternatives considered, and consequences.
|
||||
## Boundary Rules
|
||||
|
||||
Accepted decision content is immutable. A changed decision requires a new ADR
|
||||
and a superseded status/link in the old one. Navigation links may be repaired
|
||||
when specification ownership moves without rewriting historical rationale.
|
||||
Rejected architectural alternatives belong in ADRs; deferred or rejected product
|
||||
features belong in roadmaps. Do not create an ADR for every routine choice.
|
||||
### Orientation
|
||||
|
||||
## Maintenance and verification
|
||||
Link among orientation, architecture, and internal documents; maintain each
|
||||
package or behavior description in its canonical owner.
|
||||
|
||||
Update the owning current documentation in the same change that implements or
|
||||
changes behavior. When ownership moves, remove the old definition and preserve
|
||||
useful navigation links.
|
||||
### Go API And Configuration
|
||||
|
||||
Go declaration documentation owns exported symbol behavior. The configuration
|
||||
contract owns shared YAML and resolution semantics. Consumer guidance explains
|
||||
tasks and links to those contracts.
|
||||
|
||||
### Releases
|
||||
|
||||
The release policy defines requirements and invariants that every release must
|
||||
satisfy. The repository-specific release procedure defines the commands and
|
||||
workflow maintainers use to satisfy that policy. Release notes record history
|
||||
at immutable tags. Maintain current behavior in its canonical documentation,
|
||||
update it with the corresponding behavior changes, and keep release procedures
|
||||
consistent with adopted policy.
|
||||
|
||||
### Project Licensing And Upstream Attribution
|
||||
|
||||
README and release documents link to the canonical licensing and attribution
|
||||
materials under the [OSS policy](oss.md). The release procedure owns URL
|
||||
construction and publication mechanics.
|
||||
|
||||
### Contracts And Implementation
|
||||
|
||||
Go API and configuration documents define externally observable behavior.
|
||||
Internal documents explain implementation and link to the owning contract.
|
||||
|
||||
### Security Topics
|
||||
|
||||
This policy owns what documentation and examples may contain. Architecture owns
|
||||
application security invariants. The configuration and public API contracts own
|
||||
secret-classification, bootstrap, and rendering behavior. Internal docs own
|
||||
implementation mechanisms only.
|
||||
|
||||
## Architecture Decision Records
|
||||
|
||||
Use sequentially numbered ADR filenames such as
|
||||
`0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
|
||||
|
||||
1. title;
|
||||
2. status;
|
||||
3. date;
|
||||
4. context;
|
||||
5. decision;
|
||||
6. alternatives considered;
|
||||
7. consequences.
|
||||
|
||||
Treat the decision content of an accepted ADR as immutable. When a decision
|
||||
changes, create a new ADR and update the earlier ADR's status to superseded.
|
||||
Rejected architectural alternatives belong in the ADR; rejected product ideas
|
||||
belong in the roadmap. Routine choices need no ADR.
|
||||
|
||||
## Maintenance
|
||||
|
||||
When behavior changes, update its canonical owner in the same change. If
|
||||
ownership moves, remove the old definition and replace it with a link where
|
||||
navigation remains useful.
|
||||
|
||||
Before completing documentation work:
|
||||
|
||||
- verify claims against the implementation or clearly identify future design;
|
||||
- check changed local links, paths, fragments, examples, and commands;
|
||||
- preserve the distinction between policy, decisions, target behavior, and status;
|
||||
- check canonical ownership and remove stale or duplicate definitions;
|
||||
- inspect formatting and whitespace;
|
||||
- ensure no sensitive data was introduced.
|
||||
- verify affected behavior and examples;
|
||||
- check commands, flags, fields, defaults, schemas, and paths against their
|
||||
implementation;
|
||||
- keep unimplemented behavior in the roadmap, subject to the ADR exception;
|
||||
- remove stale references and validate links;
|
||||
- confirm that non-owning documents summarize and link rather than redefine;
|
||||
- confirm that no secrets or sensitive private data were added.
|
||||
|
||||
Reference in New Issue
Block a user