ReleaseKit/docs/policy/documentation.md

Documentation Policy

Base Policy Version: 1.11

Last Updated: 2026-10-05

Upstream Source: documentation.md

Purpose

This policy assigns each documentation topic to one canonical owner. Its goal is to keep ReleaseKit's documentation accurate, concise, discoverable, and resistant to drift for consumers, maintainers, developers, and coding agents.

Core Rules

One Canonical Owner

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.

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.

Current And Future Behavior

Outside docs/roadmap/, documentation describes implemented behavior only. Partial features may be described only to their implemented boundary.

Architectural constraints may govern future changes. Describe current structure from implemented behavior.

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.

Audience And Detail

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.

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.

Examples must be valid, secret-free, and tested where practical. Commands and configuration used in documentation should match the application.

Security And Privacy

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.

Canonical Ownership

Topic	Canonical owner	Owned content	Content owned elsewhere
Product orientation and minimal example	README.md	Purpose, current status, shortest useful example when implemented, and navigation, including licensing and attribution.	Complete command reference, configuration reference, operational procedures, 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.
ReleaseKit 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, 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 component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links.	General attribution policy, exception reasoning, research narratives, compliance commentary, 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.
CLI contract (if applicable)	docs/cli.md	Commands, arguments, flags, invocation semantics, and exit codes.	End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details.
Configuration contract (if applicable)	docs/config.md	Discovery, precedence, fields, defaults, environment inputs, and validation for implemented configuration.	Complete example files, CLI syntax, runtime state lifecycle, implementation details.
Exported Go API (when implemented)	Go declarations and GoDoc	Exact symbol contracts, errors, ownership, and lifecycle semantics for each facade.	Consumer walkthroughs, CLI contracts, integration protocols, and internal mechanics.
Consumer guidance for the public Go API (if applicable)	docs/consumers/	Task-oriented public Go API usage, minimal examples, and consumer responsibilities.	HTTP wire semantics, external protocol contracts, internal implementation detail.
Integration contracts for external components (if applicable)	docs/integrations/	External formats and protocols, upstream and downstream contracts, logical output paths and schemas, media types, and compatibility.	Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults.
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.
Future work and implementation status	docs/roadmap/	Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns.	Implemented behavior reference and architectural decision 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 copyable artifacts	examples/	Maintained configuration, inputs, and other copyable or runnable files.	Field-by-field reference, command reference, prose explanation.

Create supporting documents for existing interfaces and responsibilities when substantive content is available. The CLI, configuration, consumer, integration, internal, example, and release-procedure owners become documents as their corresponding implementation lands. Keep implementation status in the roadmap and avoid empty owners.

Boundary Rules

Orientation

Link among orientation, architecture, and internal documents; maintain each package or behavior description in its canonical owner.

Go API, CLI, And Configuration

Go declarations and GoDoc own exact exported contracts. Consumer guidance explains tasks and links to those declarations. CLI documentation owns invocation and exit semantics; configuration documentation owns settings. Release procedures own maintainer publication and recovery workflows. Link across those owners when a task spans their boundaries.

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. The release procedure owns URL construction and publication mechanics.

Contracts And Implementation

GoDoc, CLI, configuration, and integration documents define externally observable shapes and semantics. Internal documents explain how ReleaseKit implements or consumes those contracts. Internal docs may name a field, file, or protocol to identify a dependency, but must link to its canonical contract for the definition.

Security Topics

This policy owns what documentation and examples may contain. Architecture owns selected security invariants. Public API, configuration, and integration contracts own credential supply and observable handling. 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 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.