From 76c00e32d05eb9f2f150f3554bd578192efe3a61 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 02:27:07 +0000 Subject: [PATCH] Update documentation policy from upstream --- docs/oss/attribution.md | 11 ++++++++--- docs/policy/documentation.md | 28 +++++++++++++++------------- 2 files changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index ba1abf1..0fc7516 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -119,8 +119,9 @@ Material: `docs/policy/meta.md`, `docs/policy/agents.md`, `docs/policy/documentation.md`, `docs/policy/release.md`, and `docs/policy/oss.md`; the root `AGENTS.md` orientation after the knowledge-graph instructions; and the Policy Reading Guide in `docs/development.md`, adapted for -this repository. The release policy uses baseline -`e833faddf120c789a9b45348edaf75720de16348`; the remaining material uses baseline +this repository. The documentation policy uses baseline +`beb5f191470a9daef2383981a6bfd02232490ab4`; the release policy uses +`e833faddf120c789a9b45348edaf75720de16348`; the remaining material uses `d84a38ebab26f048cafbe59a2246700c35d29843`. Copyright (C) 2026 Eric Rakestraw @@ -131,12 +132,16 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) | -[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE). +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE) | +[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/COPYRIGHT) | +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/LICENSE). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348). +[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4). + ## ReleaseKit Selected module: `go.maximumdirect.net/releasekit` at `v0.9.0` (selected Go tool; not a runtime import). diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 9c223f7..90ed29e 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -2,9 +2,9 @@ **Base Policy Version:** 1.11 -**Last Updated**: 2026-10-10 +**Last Updated**: 2026-11-07 -**Upstream Source:** [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) +**Upstream Source:** [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/docs/policy/documentation.md) ## Purpose @@ -86,7 +86,7 @@ secret values. | 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. | +| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or deferred 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. | @@ -147,14 +147,16 @@ mechanisms only. ## Architecture Decision Records -ADRs record durable architectural decisions: responsibility boundaries, -ownership, significant constraints, and the reasons for choosing them. A settled -implementation or presentation choice does not automatically belong in an ADR. -Ask whether changing the detail would alter the architecture or represent -reasonable evolution within it. Details that can evolve within the chosen -architecture belong in API or CLI contracts, implementation documentation, or -roadmaps. Describe upstream behavior as context without turning it into an -independent project guarantee. +ADRs record major architectural decisions, such as responsibility and ownership +boundaries, large-scale architectural features, or significant architectural +invariants, and the reasons for choosing them. Routine choices, implementation +or presentation decisions, and rejected suggestions do not warrant an ADR +unless they otherwise represent a significant architectural decision. Ask +whether changing the detail would alter the architecture or represent reasonable +evolution within it. Details that can evolve within the chosen architecture +belong in API or CLI contracts, implementation documentation, or roadmaps. +Describe upstream behavior as context without turning it into an independent +project guarantee. Use sequentially numbered ADR filenames such as `0001-record-architecture-decisions.md`. Follow the lightweight Nygard format: @@ -169,8 +171,8 @@ Use sequentially numbered ADR filenames such as 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. + +Roadmaps should preserve plausible future work, not rejected product ideas. ## Maintenance