diff --git a/.woodpecker/release.yml b/.woodpecker/release.yml index f30e407..e354672 100644 --- a/.woodpecker/release.yml +++ b/.woodpecker/release.yml @@ -3,11 +3,13 @@ when: steps: - name: build-release-assets - image: golang:1.25 + image: golang:1.26.11 commands: - | set -eu + export GOTOOLCHAIN=local + version="$CI_COMMIT_TAG" dist="dist" pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium" diff --git a/docs/development.md b/docs/development.md index 312d75a..731be9f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -63,6 +63,12 @@ Promptkit source, or an import of a Promptkit `internal` package. ## Baseline Validation +The Go consumer minimum is the version declared in `go.mod`, currently 1.25.5. +It is the minimum toolchain for building Scriptorium from source; the selected +Promptkit v0.12.0 dependency requires that patch level. Running a published +binary does not require a Go installation. Release validation and builds use +the separately selected toolchain in the [release procedure](release.md). + For code changes, run: ```bash diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 861ecb2..e0fe6e2 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -14,10 +14,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). ## Promptkit diff --git a/docs/policy/agents.md b/docs/policy/agents.md index 1e972e3..002bc5f 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 cd14d4f..cb7b784 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,9 +2,9 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-10-04 +**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 ad0e062..1846787 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,10 +1,10 @@ # 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 @@ -87,8 +87,8 @@ secret values. | Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, 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. | @@ -154,8 +154,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 04954e3..36220a0 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 b8f33e9..b06c762 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 @@ -64,6 +64,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. diff --git a/docs/policy/release.md b/docs/policy/release.md index 5cfb97f..a23e695 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 relase. 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 @@ -186,7 +224,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 d305c12..c18ebfa 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 801c752..baf2de8 100644 --- a/docs/release.md +++ b/docs/release.md @@ -9,11 +9,31 @@ discoverability requirements. ## Prepare The Candidate Use a POSIX shell, Git with a configured tagger identity and access to -`origin`, and a Go toolchain compatible with `go.mod`. The native host must +`origin`, and the selected release toolchain, Go 1.26.11. The native host must support Go's race detector and have its required C compiler. If Git is configured to sign tags, its signing tool and key must be available. Run from the -repository root. Provision the toolchain and module cache before offline -validation; when dependencies are not cached: +repository root. The [developer guide](development.md#baseline-validation) +explains the separate Go consumer minimum; selecting a release toolchain does +not raise that minimum. + +Install Go 1.26.11 from the [official downloads](https://go.dev/dl/) or an +equivalent package source before validation. Set `release_go_root` to its +installation directory, replacing the illustrative path below, and select it +in the release shell: + +```sh +release_go_root=/path/to/go1.26.11 +export PATH="$release_go_root/bin:$PATH" +export GOTOOLCHAIN=local +go version +``` + +The version output should identify `go1.26.11`. Keep this selection and the +hosted workflow's Go image in step when deliberately updating the release +toolchain. Ordinary contributor checks may use another compatible toolchain. + +Provision the module cache before offline validation; when dependencies are +not cached: ```sh GOWORK=off go mod download