From 53a6e0e54ca87d7257884dade50894ff6084e140 Mon Sep 17 00:00:00 2001 From: hatayama Date: Sat, 4 Jul 2026 17:29:18 +0900 Subject: [PATCH 1/2] Sync compatibility docs to the pin-based version model AGENTS.md and the CodeRabbit guidance still described deleted machinery: the dispatcherContractVersion generation, the removed check-dispatcher-contract guard, the MINIMUM_REQUIRED_* constants, and the stamped default-tools.json version. Documentation now matches the implemented model: the IPC protocolVersion pair is the only integer generation, and the project runner pin (projectRunnerVersion + minimumDispatcherVersion) is the single source for cross-component requirements. - Document the pin's two fields, who reads them, and the additive-only format discipline that keeps forced updates reachable by old dispatchers - Point the protocol-bump workflow at the pin's release-please-stamped projectRunnerVersion instead of a hand-maintained constant --- .coderabbit.yaml | 4 +++- AGENTS.md | 45 ++++++++++++++++++++++++++++++--------------- 2 files changed, 33 insertions(+), 16 deletions(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 1d2251369f..8d5bebf4bd 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -40,6 +40,8 @@ reviews: The compatibility gate is an exact protocol match, not a release-semver range. If a change makes a CLI/package from the previous protocol generation unable to interoperate, require both `cli/common/clicontract/contract.json` `protocolVersion` and `CliConstants.REQUIRED_CLI_PROTOCOL_VERSION` to be incremented in the same PR. - Do not request a protocol bump for ordinary CLI features, bug fixes, UI changes, documentation, or additive wire-format changes that older counterparts can safely ignore. `projectRunnerVersion` is release-please managed release metadata. If a PR bumps `CliConstants.REQUIRED_CLI_PROTOCOL_VERSION`, require a matching update to `CliConstants.MINIMUM_REQUIRED_PROJECT_RUNNER_VERSION` after the corresponding published project runner release tag is available, because setup must install a project runner release that advertises the required protocol. + Do not request a protocol bump for ordinary CLI features, bug fixes, UI changes, documentation, or additive wire-format changes that older counterparts can safely ignore. `projectRunnerVersion` is release-please managed release metadata. If a PR bumps `CliConstants.REQUIRED_CLI_PROTOCOL_VERSION`, the pin's `projectRunnerVersion` must point at a published project runner release that advertises the required protocol before the Unity package is released; that value is advanced by release-please when the runner release is cut, and CI (`check-protocol-minimum-version`) enforces it. + + The project runner pin (`Packages/src/project-runner-pin.json`, mirrored to `.uloop/project-runner-pin.json`) must keep exactly its current fields and evolve additively only; flag any PR that deletes or renames a pin field, because old dispatchers learn about forced updates by parsing the pin. chat: auto_reply: true diff --git a/AGENTS.md b/AGENTS.md index d45b0d4431..6a6ebd9806 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,18 +33,39 @@ compatible must not bump it. Do not touch the protocol version to "keep up with releases": -- `cli/common/clicontract/contract.json` `projectRunnerVersion`, `cli/common/tools/default-tools.json` - `version`, and `cli/dispatcher/dispatchercontract/dispatcher-contract.json` `dispatcherVersion` are stamped by - release-please only. Never edit them by hand in a feature PR. -- `CliConstants.MINIMUM_REQUIRED_PROJECT_RUNNER_VERSION` is the release that setup installs. It - must always point at a published project runner release. +- `cli/common/clicontract/contract.json` `projectRunnerVersion`, the pin files' + `projectRunnerVersion`, and `cli/dispatcher/dispatchercontract/dispatcher-contract.json` + `dispatcherVersion` are stamped by release-please only. Never edit them by hand in a feature PR. - When a protocol bump changes `CliConstants.REQUIRED_CLI_PROTOCOL_VERSION`, prepare the matching - project runner release tag first, then update `CliConstants.MINIMUM_REQUIRED_PROJECT_RUNNER_VERSION` - in the same PR. PR CI fails, and the PR warning comment stays open, until the minimum project - runner release advances to a published release that advertises the required protocol. + project runner release first. PR CI (`check-protocol-minimum-version`) fails until the pin's + `projectRunnerVersion` points at a published project runner release that advertises the + required protocol; release-please advances that value when the runner release is cut. - Runtime protocol mismatch guidance must use the unpinned CLI update path for older clients and tell newer clients to align the package and CLI releases. +## Project Runner Pin + +`Packages/src/project-runner-pin.json` (mirrored byte-identically to `.uloop/project-runner-pin.json` +by `CliPinSynchronizer`) is the single source for cross-component version requirements. It has +exactly two fields: + +- `projectRunnerVersion` — the project runner release the dispatcher must run for this package. + Stamped by release-please; never edit by hand. +- `minimumDispatcherVersion` — the semver floor the package requires of the globally installed + dispatcher. The dispatcher force-updates itself when it is older than this value, and the + package reads it (via `CliPinReader`) for setup and installation checks. This is the only + manually maintained minimum-version declaration; raise it only when the package genuinely + needs a newly published dispatcher, not because the dispatcher implementation changed. + +There is no dispatcher⇄package integer contract generation; the pin's semver floor is the only +dispatcher gate. The IPC `protocolVersion` pair described above is the only integer generation +in the system. + +Pin format discipline: the pin evolves additively only — never delete or rename an existing +field. The forced-update instruction (`minimumDispatcherVersion`) travels inside the pin, so an +old dispatcher that cannot parse a new pin never learns it must update. For the same reason the +dispatcher must stay lenient when reading pins written by older packages. + ## Generated Skill Files Do not directly edit skill files under the project-root `.agents/` or `.claude/` directories. @@ -74,13 +95,7 @@ Run `scripts/stamp-release-inputs.sh` to refresh `cli/project-runner/shared-inpu `cli/dispatcher/shared-inputs-stamp.json`, and commit the stamp updates with the change. Pull request CI runs `check-release-triggers` (authoritative rules: `releaseTriggerRules` in `cli/release-automation/internal/automation/release_trigger_guard.go`) and fails when shared -release inputs changed without the matching triggers. CI also runs `check-dispatcher-contract`, -which fails when `dispatcherContractVersion` moves backwards. - -Do not bump `dispatcherContractVersion` unless the dispatcher contract itself changes. -Do not raise Unity package `MINIMUM_REQUIRED_DISPATCHER_VERSION` or pin-file -`minimumDispatcherVersion` just because the dispatcher implementation changed; those should -advance only when the package must require a newly published dispatcher. +release inputs changed without the matching triggers. ## Windows Compatibility Guardrails From f49029c817c14a1b5e05dd91decf4cedc77338bf Mon Sep 17 00:00:00 2001 From: hatayama Date: Sun, 5 Jul 2026 15:25:52 +0900 Subject: [PATCH 2/2] Reword pin docs so additive evolution is unambiguous "Exactly two fields" and "keep exactly its current fields" read as a frozen schema, contradicting the additive-only rule in the same section. --- .coderabbit.yaml | 2 +- AGENTS.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 8d5bebf4bd..9fa858a9e6 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -42,6 +42,6 @@ reviews: Do not request a protocol bump for ordinary CLI features, bug fixes, UI changes, documentation, or additive wire-format changes that older counterparts can safely ignore. `projectRunnerVersion` is release-please managed release metadata. If a PR bumps `CliConstants.REQUIRED_CLI_PROTOCOL_VERSION`, the pin's `projectRunnerVersion` must point at a published project runner release that advertises the required protocol before the Unity package is released; that value is advanced by release-please when the runner release is cut, and CI (`check-protocol-minimum-version`) enforces it. - The project runner pin (`Packages/src/project-runner-pin.json`, mirrored to `.uloop/project-runner-pin.json`) must keep exactly its current fields and evolve additively only; flag any PR that deletes or renames a pin field, because old dispatchers learn about forced updates by parsing the pin. + The project runner pin (`Packages/src/project-runner-pin.json`, mirrored to `.uloop/project-runner-pin.json`) must preserve its existing fields and evolve additively only; flag any PR that deletes or renames a pin field, because old dispatchers learn about forced updates by parsing the pin. chat: auto_reply: true diff --git a/AGENTS.md b/AGENTS.md index 6a6ebd9806..0e1f7af702 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,8 +46,8 @@ Do not touch the protocol version to "keep up with releases": ## Project Runner Pin `Packages/src/project-runner-pin.json` (mirrored byte-identically to `.uloop/project-runner-pin.json` -by `CliPinSynchronizer`) is the single source for cross-component version requirements. It has -exactly two fields: +by `CliPinSynchronizer`) is the single source for cross-component version requirements. It +currently has two required fields: - `projectRunnerVersion` — the project runner release the dispatcher must run for this package. Stamped by release-please; never edit by hand.