From 381668568fc97e8dbeb93ea11c9d663d97d566b5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 19:56:32 +0000 Subject: [PATCH] Adopt the updated standard repository policies --- docs/development.md | 6 +++-- docs/oss/attribution.md | 6 ++--- docs/policy/agents.md | 4 +-- docs/policy/architecture.md | 4 +-- docs/policy/documentation.md | 27 ++++++++++++-------- docs/policy/meta.md | 4 +-- docs/policy/oss.md | 22 ++++++++++------ docs/policy/release.md | 49 ++++++++++++++++++++++++++++++++---- docs/policy/testing.md | 4 +-- docs/release.md | 33 ++++++++++++++++++++---- 10 files changed, 119 insertions(+), 40 deletions(-) diff --git a/docs/development.md b/docs/development.md index e4bc410..d4a440d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -16,8 +16,10 @@ commit-after-completed-work rule; it does not authorize pushing or releasing. ## Go Prerequisite -Maintained development and verification require Go 1.26. Use the official Go -1.26 toolchain before running repository commands. +The Go consumer minimum is 1.26.0, declared in `go.mod`. Maintained development +and verification use the official Go 1.26 toolchain. Release validation and +builds use the selected patch version and setup instructions in the +[release procedure](release.md#release-toolchain). ## Policy Reading Guide diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 62ea3cf..4c2e216 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -11,10 +11,10 @@ Copyright (C) 2026 Eric Rakestraw SPDX-License-Identifier: CC-BY-SA-4.0 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/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) | +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE). -[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). +[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4). ## ConfigKit diff --git a/docs/policy/agents.md b/docs/policy/agents.md index 3a8d305..1e08d88 100644 --- a/docs/policy/agents.md +++ b/docs/policy/agents.md @@ -2,9 +2,9 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md ## Purpose diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index ff71ae2..d62e77c 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,9 +2,9 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md ## Purpose And Ownership diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 825bd7f..af611b0 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,15 +1,15 @@ # Documentation Policy -**Base Policy Version:** 1.11 +**Base Policy Version:** 1.12 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md ## Purpose This policy assigns each documentation topic to one canonical owner. Its goal is -to keep Narratio's documentation accurate, concise, discoverable, and resistant +to keep this application's documentation accurate, concise, discoverable, and resistant to drift for users, operators, developers, integrators, and LLM coding agents. ## Core Rules @@ -75,19 +75,19 @@ secret values. | 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, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. | -| Project license text | `LICENSE` | Complete GPLv3 project license text. | Companion dependency 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 dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | 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, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. | -| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | +| Operations (if applicable) | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | | Troubleshooting | `docs/troubleshooting.md` | Symptom-driven diagnosis, likely causes, safe inspection, and remedies. | Canonical commands, configuration definitions, operational procedures, and integration contracts. | | 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. | +| Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. | +| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future 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. | @@ -153,8 +153,15 @@ 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. + +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 diff --git a/docs/policy/meta.md b/docs/policy/meta.md index 4eed1ef..136408e 100644 --- a/docs/policy/meta.md +++ b/docs/policy/meta.md @@ -2,9 +2,9 @@ **Base Policy Version:** 1.0 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md ## Origin And Local Authority diff --git a/docs/policy/oss.md b/docs/policy/oss.md index 89e9fca..6955b01 100644 --- a/docs/policy/oss.md +++ b/docs/policy/oss.md @@ -1,10 +1,10 @@ # Open Source Licensing And Attribution Policy -**Base Policy Version:** 1.8 +**Base Policy Version:** 1.9 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md ## Purpose And Scope @@ -74,6 +74,9 @@ individual packages. Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT) or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT) to create the project’s root `COPYRIGHT` file. +Use the COPYRIGHT examples exactly as provided, except for placeholder +substitutions and changes expressly required or authorized by this policy or +the author. Use verified project names, contribution years, and copyright holders. For another selected license, adapt the grant, SPDX expression, disclaimer, and text references together to reflect the author's selected grant. @@ -169,10 +172,15 @@ source files; the central attribution entry does not authorize stripping them. ## Discoverability -End Narratio's README with two friendly statements linking to its actual grant -in root `COPYRIGHT` and to `docs/oss/attribution.md`, using paths relative to -the README. The statements identify Narratio's GPL v3.0-or-later grant and make -the open source attribution notices discoverable. +End the project's README with two friendly statements linking to its actual +grant in `COPYRIGHT` and the attribution document. For example, for a project +with the stated license: + +```markdown +PROJECT_NAME is licensed under the [LGPL v3.0 or later](COPYRIGHT). + +[Open Source attribution notices](docs/oss/attribution.md) are available. +``` Each new checked-in release document and its hosted download page must end with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute diff --git a/docs/policy/release.md b/docs/policy/release.md index 068ad6c..8e4c46b 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,10 +1,10 @@ # Release Policy -**Base Policy Version:** 1.4 +**Base Policy Version:** 1.7 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md ## Purpose @@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an intended source revision under a fresh version. Releases should require little routine intervention, avoid repeated work, and preserve published contents. +Adopt stronger verification or reproducibility requirements through an explicit +project-specific decision justified by the intended audience and support needs. + The repository-specific commands belong in `docs/release.md`. Historical release summaries belong in `docs/releases/`. The procedure must agree with the adopted policy and link to it rather than introduce additional release requirements. @@ -59,9 +62,14 @@ requires a deliberate update to the policy and procedure where needed. For releases at or after `v1.0.0`: - a major release may make intentional incompatible changes; -- a minor release may add backward-compatible behavior; and +- a minor release may add backward-compatible behavior or raise the Go consumer + minimum as described below; and - a patch release may make backward-compatible fixes. +In this context, "backward-compatible" means only that pre-existing, valid +configurations will continue to work following the release. Behavior need not +remain strictly identical. + Before `v1.0.0`, a minor release may change a documented public, operational, configuration, data, integration, or compatibility contract when the release note explains the impact and required consumer action. A patch release must @@ -71,6 +79,36 @@ Additional compatibility promises and deliberate exceptions belong in the adopted policy or canonical contract documentation. Release notes explain changes; they do not redefine current compatibility contracts. +## Consumer Minimum And Release Toolchain + +Distinguish the minimum toolchain supported for consumers from the toolchain +maintainers use to build and validate a release. Record the consumer minimum in +the language's standard metadata and explain its support meaning in canonical +documentation. Define the selected release toolchain and its setup commands in +`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific +choices. + +For Go repositories, normally declare the initial stable release of the selected +series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum +when a dependency or an identified correctness fix requires it, and document +the reason. + +For release-policy purposes, successful build and release validation on the +selected Go patch release are sufficient to presume support across that Go +series, subject to the declared consumer minimum and concrete evidence of +incompatibility. Investigate specific compatibility concerns as they arise. + +Use the selected release toolchain for candidate validation and release builds, +including CI jobs performing those tasks. A newer validation patch version alone +leaves the consumer minimum unchanged. + +A minor release may raise the Go consumer minimum, including from one Go series +to the next, both before and after `v1.0.0`. This is an explicit exception to the +backward-compatibility requirement for minor releases. Patch releases preserve +the consumer minimum. Explain an increase's impact and required consumer action +in the release note. Other incompatible changes remain subject to the versioning +rules above. + ## Release Documentation And Preparation Every new release must include `docs/releases/.md` in the tagged @@ -206,7 +244,8 @@ release without replacing its contents or reusing its version. Maintain `docs/release.md` as a short, executable maintainer runbook. It must identify: -1. prerequisites, primary branch, and authoritative remote; +1. prerequisites, selected release toolchain, primary branch, and authoritative + remote; 2. version and release-note preparation; 3. one publication command with its selected local checks and automated guards; 4. declared deliverables, required build targets, and automation responsibilities; diff --git a/docs/policy/testing.md b/docs/policy/testing.md index c3d2e81..9b1b76e 100644 --- a/docs/policy/testing.md +++ b/docs/policy/testing.md @@ -2,9 +2,9 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-09-28 +**Last Updated**: 2026-11-17 -**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md ## Purpose diff --git a/docs/release.md b/docs/release.md index 3ecd400..103c616 100644 --- a/docs/release.md +++ b/docs/release.md @@ -7,16 +7,18 @@ The source release completes when the intended tag is successfully pushed to ## Prepare the candidate Use `main` and the authoritative Git remote `origin`. Install Git, a POSIX -shell, standard Unix build tools, and Go 1.26. Have the selected Go modules -available before offline validation. Git access must permit fetch and tag push. +shell, standard Unix build tools, and the [release toolchain](#release-toolchain). +Have the selected Go modules available before offline validation. Git access +must permit fetch and tag push. Application-provider credentials are not required; Gitea delivery credentials belong to CI. Choose an unused stable `vMAJOR.MINOR.PATCH` under the [compatibility rules](policy/release.md#versioning-and-compatibility). Narratio -is past v1.0.0, so intentional CLI or configuration breaks require a major -release. Update affected canonical documentation with the change. Write the -matching `docs/releases/vMAJOR.MINOR.PATCH.md` with a short summary and any +is past v1.0.0; apply the policy's effective-configuration compatibility +definition and Go consumer-minimum exception. Update affected canonical +documentation with the change. Write the matching +`docs/releases/vMAJOR.MINOR.PATCH.md` with a short summary and any relevant compatibility impact or upgrade action; choose sections to suit the release. @@ -39,6 +41,27 @@ before tagging; record its exact commit if needed: git rev-parse HEAD ``` +## Release toolchain + +The selected release toolchain is Go 1.26.7, matching the validation and build +jobs in `.woodpecker/release.yml`. With an official Go installation available, +select it before candidate validation and publication: + +```sh +export GOTOOLCHAIN=go1.26.7 +go version +``` + +Go downloads the selected toolchain if needed. Complete that setup and module +preparation before offline candidate validation. Keep this selection and the +release CI images aligned when deliberately updating the release toolchain. + +The consumer minimum remains Go 1.26.0 as declared in `go.mod`. +Successful release validation on the selected patch establishes presumed +support across that series, subject to the declared minimum and concrete +evidence of incompatibility, under the +[release policy](policy/release.md#consumer-minimum-and-release-toolchain). + ## Publish From a clean `main` checkout at the pushed candidate, run one command: