Adopt upstream ADR guidance and revise durable documentation requirements
This commit is contained in:
@@ -5,7 +5,8 @@
|
|||||||
Material: All documents under `docs/policy/`, root `AGENTS.md`, and the Policy
|
Material: All documents under `docs/policy/`, root `AGENTS.md`, and the Policy
|
||||||
Reading Guide in `docs/development.md`, adapted for this repository.
|
Reading Guide in `docs/development.md`, adapted for this repository.
|
||||||
`docs/policy/release.md` incorporates revision
|
`docs/policy/release.md` incorporates revision
|
||||||
`e833faddf120c789a9b45348edaf75720de16348`; the remaining listed material
|
`e833faddf120c789a9b45348edaf75720de16348`; `docs/policy/documentation.md`
|
||||||
|
incorporates revision `beb5f191470a9daef2383981a6bfd02232490ab4`; the remaining listed material
|
||||||
incorporates revision `d84a38ebab26f048cafbe59a2246700c35d29843`.
|
incorporates revision `d84a38ebab26f048cafbe59a2246700c35d29843`.
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
@@ -16,12 +17,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) |
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
|
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
|
||||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) |
|
[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/d84a38ebab26f048cafbe59a2246700c35d29843).
|
||||||
|
|
||||||
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
|
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
|
||||||
|
|
||||||
|
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4).
|
||||||
|
|
||||||
## ConfigKit
|
## ConfigKit
|
||||||
|
|
||||||
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.7.1`.
|
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.7.1`.
|
||||||
|
|||||||
@@ -2,8 +2,8 @@
|
|||||||
|
|
||||||
**Base Policy Version:** 1.11
|
**Base Policy Version:** 1.11
|
||||||
|
|
||||||
**Last Updated**: 2026-09-28
|
**Last Updated**: 2026-11-08
|
||||||
**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
|
**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/docs/policy/documentation.md)
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
@@ -86,7 +86,7 @@ secret values.
|
|||||||
| 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. |
|
| 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. |
|
||||||
| Contributor change recipes | Relevant files under `docs/internal/`, including `docs/internal/cli-config.md`, `docs/internal/modules.md`, and `docs/internal/validators.md` | Concrete editing and validation steps for each component. | Contributor orientation, global policy, and definitions of external contracts. |
|
| Contributor change recipes | Relevant files under `docs/internal/`, including `docs/internal/cli-config.md`, `docs/internal/modules.md`, and `docs/internal/validators.md` | Concrete editing and validation steps for each component. | Contributor orientation, global policy, and definitions of external contracts. |
|
||||||
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
|
| 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. |
|
| 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. |
|
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
|
||||||
|
|
||||||
@@ -154,8 +154,15 @@ Use sequentially numbered ADR filenames such as
|
|||||||
|
|
||||||
Treat the decision content of an accepted ADR as immutable. When a decision
|
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.
|
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.
|
ADRs should be reserved for major architectural decisions, such as ownership
|
||||||
|
boundaries, large-scale architectural features, or invariants that rise to
|
||||||
|
the level of architectural significance. Routine choices, implementation
|
||||||
|
decisions, and rejected suggestions do not warrant an ADR unless they
|
||||||
|
otherwise represent a significant architectural decision.
|
||||||
|
|
||||||
|
Roadmaps should preserve plausible future work, not rejected product
|
||||||
|
ideas.
|
||||||
|
|
||||||
## Maintenance
|
## Maintenance
|
||||||
|
|
||||||
|
|||||||
@@ -119,12 +119,14 @@ semantics remain part of the open decision below.
|
|||||||
|
|
||||||
### Durable Decision Record
|
### Durable Decision Record
|
||||||
|
|
||||||
Completion requires recording the scope model and its rationale in an accepted
|
Completion requires recording the scope model in durable documentation before
|
||||||
[ADR](../adr/README.md) before retiring this roadmap. Put the enduring
|
retiring this roadmap. Put the enduring classification rule and its rationale
|
||||||
classification rule in the [architecture policy](../policy/architecture.md),
|
in the [architecture policy](../policy/architecture.md); keep the implemented
|
||||||
linked to that ADR; keep the implemented per-field scope and fallback contracts
|
per-field scope and fallback contracts in the [configuration reference](../config.md).
|
||||||
in the [configuration reference](../config.md). The roadmap continues to own
|
These configuration design decisions do not require an ADR. Reserve ADRs for
|
||||||
implementation status until the feature lands.
|
major architectural decisions under the
|
||||||
|
[documentation policy](../policy/documentation.md#architecture-decision-records).
|
||||||
|
The roadmap continues to own implementation status until the feature lands.
|
||||||
|
|
||||||
Update the [configuration change guide](../internal/cli-config.md) to require
|
Update the [configuration change guide](../internal/cli-config.md) to require
|
||||||
classifying each new setting by consumer lifecycle, specifying its inheritance
|
classifying each new setting by consumer lifecycle, specifying its inheritance
|
||||||
@@ -175,7 +177,7 @@ Exercise the selected request and validation overrides through stage consumers,
|
|||||||
including independent budgets without changing shared backend admission or the
|
including independent budgets without changing shared backend admission or the
|
||||||
initial transcript sections. Cover all validation-profile fallback cases above
|
initial transcript sections. Cover all validation-profile fallback cases above
|
||||||
and preserve the distinction between explicit and derived values in inspection.
|
and preserve the distinction between explicit and derived values in inspection.
|
||||||
Confirm that the durable policy, ADR, configuration contracts, and contributor
|
Confirm that the durable policy, configuration contracts, and contributor
|
||||||
guidance are in place before declaring this feature complete.
|
guidance are in place before declaring this feature complete.
|
||||||
|
|
||||||
## Open Decisions
|
## Open Decisions
|
||||||
|
|||||||
Reference in New Issue
Block a user