conformance-kit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6e770de2e65a548378c2950a8f74f1a6c56b16609ac26664ec6296bd17f2bbd
-  data.tar.gz: 2d97f05248db1e51dd036b286ace5bad7c75ab2a9de2443eec7589165a4bd700
+  metadata.gz: 6e74bc1ed523498fd8aa7cd04191a6b13b690568c21a5a16627c0d2d147afb15
+  data.tar.gz: 9138ad7259e5f81442f50c9fab3e6a9b3fd08a3569a4861f27e62bc945f446b5
 SHA512:
-  metadata.gz: f008a9934b689d327cef7f99483618e389da37ee375462bd2ab1097fba758106578cdd3f2b36265ba000487383473e35613c8dfbc1da413baed8216e517f005d
-  data.tar.gz: 3f70b113493211202cf08ee4e66fc251417ff998d481a2944d465f4cf605cdf93235541f8cc152d3ac87e1eb8af1c88c268ed0a6b4e54d1f1a0ccc7ea7f197ab
+  metadata.gz: acb89af04013c0b5e8efc69da423c53f794c9305359c0f7dfe131066cfa9f47f6436e586c6de74d80272a25a3f8f29deab16831045c37971d30815968b6286e0
+  data.tar.gz: 4ac36fc7dbef17b06b1c2fd7bca8c38ee6f915a910324f1173602af05d51ed571207c2f02536cd8d926adebe2d9e54a3c484dc606976d1bf199424860cedb209

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0
+
+Breaking (pre-1.0): `conformance.yml` is a reusable workflow that each repo calls, instead of one an org ruleset requires. It runs on `workflow_call` only. A repo adds a caller pinned to a release tag (`uses: zoolutions/conformance-kit/.github/workflows/conformance.yml@vX.Y.Z`, see the README) and makes `conformance / Conformance settings` and `conformance / Conformance (Ruby 4.0)` required checks in its own branch ruleset. Repos outside zoolutions can use it the same way.
+
+- The version handshake reads `job.workflow_ref` (the called workflow's own tag) instead of `github.workflow_ref` (the caller's).
+- This repo calls its own workflow through `.github/workflows/conformance-self.yml`.
+
 ## 0.2.0
 
 Breaking (pre-1.0): the reusable workflows `ractor.yml` and `probes.yml` are replaced by `conformance.yml`, which an org ruleset requires at a release tag. A repo opts in with `.conformance.yml`, `gem "conformance-kit", "~> 0.2"` and `gem "rubocop-thread_safety", ">= 0.8"` in its Gemfile, and `inherit_gem: { conformance-kit: config/rubocop.yml }` in `.rubocop.yml` (`conformance-kit doctor` checks all three); it needs no workflow edits.

data/README.md

@@ -16,7 +16,7 @@ Background, the finalize-at-boot pattern and the settled decisions: [zoolutions/
 ```ruby
 # Gemfile
 group :development, :test do
-  gem "conformance-kit", "~> 0.2", require: false
+  gem "conformance-kit", "~> 0.3", require: false
   gem "rubocop-thread_safety", ">= 0.8", require: false # for config/rubocop.yml
   gem "async", require: false                 # optional: runs the fiber example
 end
@@ -172,17 +172,55 @@ Turns on the six `rubocop-thread_safety` cops (`ClassAndModuleAttributes`, `Clas
 
 ## Enforcement
 
-Conformance is enforced by **one workflow in this repo**, `.github/workflows/conformance.yml`, which a zoolutions org ruleset requires at a release tag (`conformance.yml@refs/tags/vX.Y.Z`). A repo needs no workflow of its own: it opts in with
+Conformance runs as **one reusable workflow in this repo**, `.github/workflows/conformance.yml`. Any repo can call it, inside zoolutions or not. A repo opts in with
 
 1. `.conformance.yml` (above),
-2. the Gemfile lines (`conformance-kit ~> 0.2`, `rubocop-thread_safety >= 0.8`),
-3. `inherit_gem: { conformance-kit: config/rubocop.yml }` in `.rubocop.yml`.
+2. the Gemfile lines (`conformance-kit ~> 0.3`, `rubocop-thread_safety >= 0.8`),
+3. `inherit_gem: { conformance-kit: config/rubocop.yml }` in `.rubocop.yml`,
+4. a caller, pinned to a release tag:
 
-The workflow runs on `pull_request` and `merge_group`, with two jobs:
+```yaml
+# .github/workflows/conformance.yml
+name: Conformance
+
+on:
+  pull_request:
+  merge_group:
+
+permissions:
+  contents: read
+
+jobs:
+  conformance:
+    uses: zoolutions/conformance-kit/.github/workflows/conformance.yml@v0.3.0
+```
+
+To make it a merge requirement, add `conformance / Conformance settings` and `conformance / Conformance (Ruby 4.0)` to the required status checks in the repo's branch ruleset. Require both: if the settings job fails, the gate is skipped, and a skipped check does not block a merge. The prefix is the caller's job id (`conformance` above) and the Ruby is `ractor.ruby`, so the names change with either. Leave the probes out: they never fail. A repo or org that only allows selected actions must allow `zoolutions/conformance-kit/.github/workflows/conformance.yml@*`.
+
+The workflow has three jobs:
 
+- **Conformance settings** reads `ractor.ruby` and `ractor.working_directory`.
 - **Conformance (Ruby `ractor.ruby`)**, the gate: the version handshake, then `bundle exec conformance-kit check`. A `postgres:18` service (user and password `postgres`, port 5432) is always up; the workflow exports nothing, so `ractor.env` and `ractor.setup` wire it.
 - **Compiler probes (report-only)**: `rubocop_spinel` (gem-installed in the probe, never in your Gemfile), `spinel-compat probe <probes.gem_name> --dir .` and, when `probes.roundhouse_app` is set, `roundhouse check` (the release tarball, checked against a pinned SHA-256). Every probe continues on error; the reports go to the run summary and a `conformance-probes` artifact. It never fails a build, and it skips with a notice when `probes.gem_name` is unset.
 
+### Staying current
+
+Dependabot bumps both pins: the `uses:` tag (`github-actions`) and the gem (`bundler`), in separate pull requests.
+
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: { interval: weekly }
+  - package-ecosystem: bundler
+    directory: /
+    schedule: { interval: weekly }
+```
+
+Merge the gem bump first: after a minor or major release the workflow bump fails the version handshake until the lockfile has caught up.
+
 ### `conformance-kit check`, the local equivalent
 
 ```bash
@@ -191,7 +229,7 @@ bundle exec conformance-kit doctor   # the static checks only
 bundle exec conformance-kit config probes.gem_name
 ```
 
-`check` stops at the first failing stage, names it, and exits with its status. Run it before flipping a repo: what passes here passes the workflow (on the same Ruby).
+`check` stops at the first failing stage, names it, and exits with its status. Run it before adding the caller: what passes here passes the workflow (on the same Ruby).
 
 `doctor` checks that `.conformance.yml` exists, is valid and sets `audit.namespace`; that `.rubocop.yml` inherits `conformance-kit: config/rubocop.yml`; and that `rubocop-thread_safety` resolves at `>= 0.8`. Each problem names its fix. `--expect X.Y` also checks the resolved `conformance-kit` is at least `X.Y`.
 
@@ -205,7 +243,7 @@ bundle exec conformance-kit config probes.gem_name
 
 ### The version handshake
 
-The behaviour a repo is held to comes from the `conformance-kit` in its lockfile; only the plumbing comes from the workflow tag. So a stale lockfile cannot pass a newer workflow vacuously, the workflow reads its own tag from `github.workflow_ref` and fails with "bump conformance-kit to ~> X.Y" when the repo resolves anything older than `X.Y`. The version is derived, never stored: a release bumps only the ruleset's `ref`. On a ref that is not a `refs/tags/v*` tag (this repo's own pull requests) the handshake is skipped with a notice. That `github.workflow_ref` carries the tag for a ruleset-required workflow is verified in the rollout pilot; until then, treat the handshake as pending validation.
+The behaviour a repo is held to comes from the `conformance-kit` in its lockfile; only the plumbing comes from the workflow tag. So that a stale lockfile cannot pass a newer workflow vacuously, the workflow reads its own tag from `job.workflow_ref` (the called workflow's ref; `github.workflow_ref` is the caller's) and fails with "bump conformance-kit to ~> X.Y" when the repo resolves anything older than `X.Y`. The version is derived, never stored. When the caller pins anything other than a `vX.Y.Z` tag (a branch, a commit SHA, or this repo's own `./` caller) the handshake is skipped with a notice, and so it is on GitHub Enterprise Server, which has no `job.workflow_ref`. That a tag-pinned call carries the tag is GitHub's documented behaviour; it has not been seen on a run yet, since v0.3.0 is the first tag that can be called. Until it has, treat the handshake as pending validation.
 
 ## Development
 

data/lib/conformance_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConformanceKit
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conformance-kit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mhenrixon
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Shared RSpec examples, a per-Ractor storage shim, a class-state audit,
-  RuboCop configs and an org-required CI workflow that hold a gem to explicit thread-safe,
+  RuboCop configs and a reusable CI workflow that hold a gem to explicit thread-safe,
   fiber-safe and Ractor-clean tiers.
 email:
 - mikael@mhenrixon.com