From dfb025b52e150719662e6eedb6de34a8eab871c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=B5nis=20Ormisson?= Date: Tue, 4 Aug 2026 20:36:13 +0300 Subject: [PATCH 1/3] Harden specification release controls --- .github/workflows/ci.yml | 9 ++++++-- README.md | 2 +- RELEASING.md | 45 ++++++++++++++++++++++++++++++++++++++++ ROADMAP.md | 7 ++++--- 4 files changed, 57 insertions(+), 6 deletions(-) create mode 100644 RELEASING.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8cd1ff1..98f0cc6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,12 +4,17 @@ on: push: pull_request: +permissions: + contents: read + jobs: specification: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 - - uses: actions/setup-python@v7 + # v7.0.0: https://github.com/actions/checkout/commit/3d3c42e5aac5ba805825da76410c181273ba90b1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + # v7.0.0: https://github.com/actions/setup-python/commit/5fda3b95a4ea91299a34e894583c3862153e4b97 + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 with: python-version: "3.13" - run: python tools/validate_repository.py diff --git a/README.md b/README.md index 1db09e7..3d4fed6 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ remains an explicitly unsupported [future dialect](docs/mssql-dialect-roadmap.md OpenStatSpec does not define long-form cells, EAV storage, table splitting, reshaping, automatic harmonization, or questionnaire/study entities. It does not infer respondent keys or combine datasets. All conformant database-object identifiers are generic; the double-underscore prefix is reserved for standard technical identifiers. -[Versioning](VERSIONING.md) defines compatibility and release rules. [Roadmap](ROADMAP.md) tracks remaining project work and maintainer setup. +[Versioning](VERSIONING.md) defines compatibility and release rules. [Releasing](RELEASING.md) defines the maintainer release checklist. [Roadmap](ROADMAP.md) tracks remaining project work and maintainer setup. ## Optional SQL transformation workflow diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..b374ed9 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,45 @@ +# Releasing OpenStatSpec + +This checklist governs releases of this specification repository. It does not +publish an implementation package and does not substitute for implementation +or adapter conformance evidence. + +## Before preparing a release + +- Choose an exact reviewed commit on the appropriate branch and record its + full commit ID. Stable tags use the convention `vX.Y.Z`. +- Keep maintenance releases on their maintained release branch. Merge the + equivalent corrective change to `main` separately when it is also needed by + the next minor release; do not make a maintenance tag point at unrelated + unreleased `main` work. +- Run the repository validation at that exact commit and confirm the required + CI run for that commit is successful. A green run for a nearby commit is not + sufficient. +- For a release that claims adapter, dialect, transformation, or syntax-front + end support, collect the required adapter conformance and service-matrix + evidence for that same specification commit. Do not convert a + `release_candidate` claim into `released` before those gates pass. +- Confirm the changelog, versioning impact, and release notes describe only + the included specification changes. + +## Tag and release + +- Create `vX.Y.Z` only after the exact release commit has passed CI. Use a + signed annotated tag where signing is available, or create the tag through a + protected tag rule restricted to release maintainers. Do not move or reuse a + published tag. +- Create the GitHub release as a draft from that exact tag and verify the tag + target, title, notes, links, and any release assets before publication. +- Publish the release only when its GitHub release is immutable. If immutable + releases or protected tags are unavailable, stop and restore those controls + before publishing. + +## After publication + +- Verify the published release resolves to the intended full commit ID and + that the tag and release are immutable or protected as intended. +- Verify the tag-triggered CI run is successful and that the release notes are + visible from the repository release page. +- Record any remaining future-release gates in the roadmap. Publishing a + specification release never completes pending adapter or service-matrix + evidence by itself. diff --git a/ROADMAP.md b/ROADMAP.md index c1de578..43cfbca 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -28,8 +28,8 @@ Prerequisite: the core mapping and canonical fixtures are stable enough to test - [x] Add continuous checks for specification links, schema examples, fixtures, and adapter conformance once the relevant repositories exist. - [x] Define versioning and compatibility guidance for the specification and profiles. -- [x] Publish release notes and tagged specification releases; `v0.2.0` is the - current public specification release. +- [x] Publish release notes and tagged specification releases; `v0.2.1` is the + current public specification release and is immutable. - [ ] Expand implementation, dialect-profile, and adoption documentation from real adapter experience. ## 5. Future adapters @@ -108,5 +108,6 @@ These are maintainer actions, not implementation tasks for the specification rep - [x] Register and publish the OpenStatSpec PHP package through Packagist. The public package establishes the registry setup; repository update ownership still needs release-process verification. -- [ ] Decide the release owner(s), tag naming convention, and release checklist for every repository. +- [x] Define the specification release tag convention and maintainer checklist in + [RELEASING.md](RELEASING.md); release ownership remains an operational control. - [ ] Protect the default branches and ensure release tags are created only by the agreed release workflow; `main` is currently unprotected. From 1872e0e5b0ebee6a2d63b50111c3841bcbee866d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=B5nis=20Ormisson?= Date: Tue, 4 Aug 2026 20:45:03 +0300 Subject: [PATCH 2/3] Clarify immutable release verification --- .github/workflows/ci.yml | 4 +++- CHANGELOG.md | 10 +++++++--- RELEASING.md | 8 +++++--- ROADMAP.md | 2 +- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 98f0cc6..43474af 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,8 +11,10 @@ jobs: specification: runs-on: ubuntu-latest steps: - # v7.0.0: https://github.com/actions/checkout/commit/3d3c42e5aac5ba805825da76410c181273ba90b1 + # v7.0.1: https://github.com/actions/checkout/commit/3d3c42e5aac5ba805825da76410c181273ba90b1 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false # v7.0.0: https://github.com/actions/setup-python/commit/5fda3b95a4ea91299a34e894583c3862153e4b97 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 with: diff --git a/CHANGELOG.md b/CHANGELOG.md index 42df551..cd5a4ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,9 +17,13 @@ Until a protected or signed `v0.3.0` tag targets this work, implementations MUST action followed by an existing-target apply with no automatic Dolt commit. - Added independent synthetic golden fixtures, hashes, examples, and repository validation gates for the new contracts. -- Corrected the SPSS Syntax Frontend 0.1 schema's `$defs` and `$ref` keywords - so typed value-label values are constrained as the existing contract states; - this is eligible for a patch-series backport under the schema-defect policy. + +## v0.2.1 - 2026-08-04 + +- Corrected the SPSS Syntax Frontend 0.1 schema's `$defs` and `$ref` + keywords so typed value-label values are constrained as the existing + contract states. This maintenance release contains no Transformation Plan or + SPSS Syntax Frontend 0.2 work. ## v0.2.0 - 2026-07-31 diff --git a/RELEASING.md b/RELEASING.md index b374ed9..82b1beb 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -3,6 +3,8 @@ This checklist governs releases of this specification repository. It does not publish an implementation package and does not substitute for implementation or adapter conformance evidence. +The repository release maintainer with repository-admin authority is responsible +for completing this checklist and preserving the release controls it requires. ## Before preparing a release @@ -30,14 +32,14 @@ or adapter conformance evidence. published tag. - Create the GitHub release as a draft from that exact tag and verify the tag target, title, notes, links, and any release assets before publication. -- Publish the release only when its GitHub release is immutable. If immutable +- Before publishing, verify the repository immutable-releases setting is enabled. +- Publish the release only after that setting is confirmed; if immutable releases or protected tags are unavailable, stop and restore those controls before publishing. ## After publication -- Verify the published release resolves to the intended full commit ID and - that the tag and release are immutable or protected as intended. +- Verify GitHub reports immutable true for the published release and its tag as the intended full commit ID. - Verify the tag-triggered CI run is successful and that the release notes are visible from the repository release page. - Record any remaining future-release gates in the roadmap. Publishing a diff --git a/ROADMAP.md b/ROADMAP.md index 43cfbca..1a84537 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -109,5 +109,5 @@ These are maintainer actions, not implementation tasks for the specification rep public package establishes the registry setup; repository update ownership still needs release-process verification. - [x] Define the specification release tag convention and maintainer checklist in - [RELEASING.md](RELEASING.md); release ownership remains an operational control. + [RELEASING.md](RELEASING.md); the repository release maintainer with repository-admin responsibility owns release-process controls. - [ ] Protect the default branches and ensure release tags are created only by the agreed release workflow; `main` is currently unprotected. From 5f004a23bb5b6889716544f168e1ca85ae7c31e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=B5nis=20Ormisson?= Date: Tue, 4 Aug 2026 20:55:16 +0300 Subject: [PATCH 3/3] Clarify release tag and validation boundaries --- README.md | 2 +- RELEASING.md | 23 ++++++++++++++--------- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3d4fed6..eda678d 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ to be provisioned separately before an in-place transformation apply. Implementations must preflight target capabilities before import. If the target cannot faithfully create one wide table because of column, identifier, string, or row limits, import must fail atomically with a machine-readable capability diagnostic. It must never silently truncate, drop, split, transpose, pivot, or transform source data. -This specification repository publishes only normative Transformation Plan and SPSS syntax frontend schemas, documentation, and declarative fixtures. Executable validation or behavioral conformance code, including parser, SQL-engine, transaction, and adapter behavior, belongs in each implementation or adapter repository. +This specification repository publishes normative Transformation Plan and SPSS syntax frontend schemas, documentation, declarative fixtures, and its own structural/hash/fixture validation in tools/validate_repository.py. It does not contain executable implementation or behavioral conformance code: parser, SQL-engine, transaction, and adapter behavior belong in each implementation or adapter repository. ## Who it is for diff --git a/RELEASING.md b/RELEASING.md index 82b1beb..f269b52 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -3,6 +3,7 @@ This checklist governs releases of this specification repository. It does not publish an implementation package and does not substitute for implementation or adapter conformance evidence. + The repository release maintainer with repository-admin authority is responsible for completing this checklist and preserving the release controls it requires. @@ -26,20 +27,24 @@ for completing this checklist and preserving the release controls it requires. ## Tag and release -- Create `vX.Y.Z` only after the exact release commit has passed CI. Use a - signed annotated tag where signing is available, or create the tag through a - protected tag rule restricted to release maintainers. Do not move or reuse a - published tag. +- Create and push `vX.Y.Z` only after the exact release commit has passed + CI. Use the selected signed annotated-tag path where signing is available, + or the selected protected-tag path restricted to release maintainers. Do not + move or reuse a published tag. +- Wait for the CI run in that exact tag context to succeed before creating or + publishing the immutable GitHub release; a branch-commit CI result is not a + substitute for the tag-context result. - Create the GitHub release as a draft from that exact tag and verify the tag target, title, notes, links, and any release assets before publication. -- Before publishing, verify the repository immutable-releases setting is enabled. -- Publish the release only after that setting is confirmed; if immutable - releases or protected tags are unavailable, stop and restore those controls - before publishing. +- Before publishing, verify the repository immutable-releases setting is + enabled. If that setting or the selected signed-or-protected tag path is + unavailable, stop and restore the missing selected control before publishing. +- Publish the release only after those checks are confirmed. ## After publication -- Verify GitHub reports immutable true for the published release and its tag as the intended full commit ID. +- Verify GitHub reports immutable true for the published release and its tag as + the intended full commit ID. - Verify the tag-triggered CI run is successful and that the release notes are visible from the repository release page. - Record any remaining future-release gates in the roadmap. Publishing a