From de3a0553800b0c9b99952887d3507d150ff0a19a Mon Sep 17 00:00:00 2001 From: Lukasz Klimek <842586+lklimek@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:25:02 +0000 Subject: [PATCH 1/6] docs(release): version by RPC, ABCI, P2P/consensus and block contracts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Base SemVer on the contracts that node operators and Dash Platform depend on. A backward-incompatible change to RPC, ABCI, P2P/consensus or the block format is a major, including a new consensus version activated by a chain parameter. Exported Go APIs, configuration and CLI no longer affect the version; the changelog still documents them. Persisted data is not versioned, but storage changes must migrate automatically. 🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig --- .agents/skills/tenderdash-release/SKILL.md | 47 ++++++++++++++-------- CONTRIBUTING.md | 3 +- README.md | 8 ++-- RELEASES.md | 27 +++++++++++-- 4 files changed, 62 insertions(+), 23 deletions(-) diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index faadfd06c..de399e446 100644 --- a/.agents/skills/tenderdash-release/SKILL.md +++ b/.agents/skills/tenderdash-release/SKILL.md @@ -63,27 +63,42 @@ tree is not a new feature; a patch-equivalent backport may already be released. Explain cherry-picks, merges, existing release bumps, and partial reverts rather than counting them twice. Pure release metadata is not a new compatibility change. -Assess these contracts explicitly: +The software version (`TMVersionDefault`) is decided by four versioned contracts: -| Contract | Evidence and decision | +| Versioned contract | Evidence and decision | | --- | --- | -| Exported non-internal Go API and RPC | Removed/changed types, methods, fields, response semantics, caller migration | +| RPC | Methods, parameters, responses and their semantics | | ABCI | Application methods, messages, return handling and app coordination; review `ABCISemVer` separately | -| P2P and consensus | Message/channel formats, proposer selection, peer compatibility; review `P2PProtocol` | -| Blocks, votes, commits, state validity | Serialization/hash/signing/validity changes and persisted data; review `BlockProtocol` | -| Configuration, CLI, storage | Previously supported settings or workflows rejected, defaults changed, database migration/rollback | -| Dash Platform integration | Required Drive/ABCI/Dashmate updates, network activation, mixed-version operation, operator rollout | - -For the current 1.x-and-later software contract: incompatible supported behavior -requires a major; compatible new functionality requires a minor; compatible fixes -require a patch. A security or consensus fix is not automatically patch-safe. -Tightened validation that breaks supported configuration or application behavior -must be called out and classified from the actual contract. Internal-only work -may need no release; do not manufacture a bump for an analysis request. +| P2P and consensus | Message/channel formats, consensus rules, proposer selection, consensus versions, peer compatibility; review `P2PProtocol` | +| Block format | Serialization, hashes, signing and validity of blocks, votes and commits; review `BlockProtocol` | + +- **Major:** any backward-incompatible change to a versioned contract. This + includes a new consensus version (e.g. `CONSENSUS_VERSION_3`) even when a chain + parameter activates it, any change after which older nodes cannot follow the + network, a removed or semantically changed RPC, and an `ABCISemVer` major. +- **Minor:** a backward-compatible extension of a versioned contract (new optional + fields, RPC methods, or parameters that leave existing networks unchanged). +- **Patch:** fixes that change no versioned contract. A security or consensus fix + is not automatically patch-safe; classify it from its actual contract effect. + +These do not affect the version, but the changelog must describe them with any +operator action: exported Go APIs (not consumed as a library), configuration and +CLI (including removed settings and tightened validation), tooling, CI and docs. +Persisted data is not versioned either: storage changes must migrate +automatically and invisibly to node operators. Data is largely recoverable by +resync and rollback is an edge case, but a change that needs manual migration is +a release blocker, not a version decision. Also record the Dash Platform +integration: required Drive/ABCI/Dashmate updates, network activation, +mixed-version operation and operator rollout. Internal-only work may need no +release; do not manufacture a bump for an analysis request. Protocol counters and `ABCISemVer` are independent of `TMVersionDefault`: explain -whether each must change, and why. Do not mechanically increment every counter, -or use a software major to conceal an unhandled network compatibility change. +whether each must change, and why. `ABCISemVer` is the ABCI contract's own +SemVer (Drive accepts `^major.minor`), `P2PProtocol` changes with P2P messages or +behavior, and `BlockProtocol` changes only with the block format; nodes enforce it +strictly, so its bump also implies a software major. Do not mechanically increment +every counter, or use a software major to conceal an unhandled network +compatibility change. If the diff contains unresolved compatibility questions, report them and defer publication until the Platform/release owner resolves them. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4fc60a848..a6170f333 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -165,7 +165,8 @@ work. Mark it ready for review when the change and its explanation are ready. Use [Conventional Commits](https://www.conventionalcommits.org/) for commit and PR titles, for example `fix(consensus): validate the proposal before voting`. Use `!` and explain migration requirements for an incompatible change. These -summaries help readers; the actual compatibility review determines release scope. +summaries help readers; the actual compatibility review determines release scope +(see the [versioning policy](RELEASES.md#versioning-policy)). A normal development PR does not update the release version or `CHANGELOG.md`. Read the final diff, address verified findings and update the tests and PR diff --git a/README.md b/README.md index b024c2882..c11792db5 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,11 @@ See the [installation instructions](docs/introduction/install.md), Building from source requires Go 1.27.3 or newer and the BLS native dependency; `make build` handles the dependency build. -Tenderdash uses Semantic Versioning for releases. Compatibility review includes -exported Go APIs, RPC, ABCI, P2P and block protocols, persisted data, and operator -configuration. Release notes describe migration and coordinated rollout needs. +Tenderdash uses Semantic Versioning for releases. The version follows the RPC, +ABCI, P2P/consensus and block-format contracts: a backward-incompatible change to +any of them, including a new consensus version, is a major release. Exported Go +APIs and configuration do not affect the version, and storage changes migrate +automatically. Release notes describe migration and coordinated rollout needs. The [project release skill](.agents/skills/tenderdash-release/SKILL.md) reviews actual changes before choosing a version; commit prefixes alone do not decide it. diff --git a/RELEASES.md b/RELEASES.md index 6d6112a38..b967556e6 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -36,9 +36,30 @@ A fix for another deployed line starts from its exact released tag and requires an explicit Platform support decision rather than automatic maintenance promises. Release tags remain `vX.Y.Z`; prereleases use `vX.Y.Z-dev.N`. The skill evaluates -SemVer from compatibility, not branch names or `feat`/`fix` labels. It separately -reviews `P2PProtocol`, `BlockProtocol`, and `ABCISemVer`; a software version bump -does not update those contracts automatically. +SemVer from compatibility, not branch names or `feat`/`fix` labels. + +## Versioning policy + +The software version is decided only by these contracts: RPC, ABCI, P2P and +consensus, and the block format. + +- **Major:** a backward-incompatible change to any of them. A new consensus + version (for example `CONSENSUS_VERSION_3`) is a major even when a chain + parameter activates it, as are changes older nodes cannot follow, removed or + semantically changed RPC, and an `ABCISemVer` major. +- **Minor:** a backward-compatible extension, such as new optional fields, RPC + methods or parameters that leave existing networks unchanged. +- **Patch:** fixes that change none of these contracts. + +Exported Go APIs, configuration and CLI (including removed settings and tightened +validation), tooling, CI and documentation do not affect the version; the +changelog describes them and any operator action. Persisted data is not versioned: +storage changes must migrate automatically and invisibly to operators, since most +data can be rebuilt by resync and rollback is an edge case. + +The skill separately reviews `P2PProtocol`, `BlockProtocol`, and `ABCISemVer`; a +software version bump does not update those contracts automatically. +`BlockProtocol` is enforced strictly, so bumping it also requires a major. Full-release promotion and stable-to-dev synchronization should preserve ancestry. Master currently has protection rules that must be reconciled with From fcc64185ad095260f71aee850f1769864a935413 Mon Sep 17 00:00:00 2001 From: Lukasz Klimek <842586+lklimek@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:25:25 +0000 Subject: [PATCH 2/6] docs(release): require explicit confirmation for BlockProtocol changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A BlockProtocol change is a full hard fork; the release skill must stop and get explicit confirmation of that specific change. 🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig --- .agents/skills/tenderdash-release/SKILL.md | 7 ++++++- RELEASES.md | 3 +++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index de399e446..0c7e2a069 100644 --- a/.agents/skills/tenderdash-release/SKILL.md +++ b/.agents/skills/tenderdash-release/SKILL.md @@ -96,7 +96,12 @@ Protocol counters and `ABCISemVer` are independent of `TMVersionDefault`: explai whether each must change, and why. `ABCISemVer` is the ABCI contract's own SemVer (Drive accepts `^major.minor`), `P2PProtocol` changes with P2P messages or behavior, and `BlockProtocol` changes only with the block format; nodes enforce it -strictly, so its bump also implies a software major. Do not mechanically increment +strictly, so its bump also implies a software major. + +A `BlockProtocol` change is a red flag: it is a full hard fork that invalidates +existing chains for nodes on either side. Never bump it, or prepare a release that +changes it, without the user's explicit confirmation of that specific change; +stop and ask even when a release was otherwise authorized. Do not mechanically increment every counter, or use a software major to conceal an unhandled network compatibility change. If the diff contains unresolved compatibility questions, report them and defer diff --git a/RELEASES.md b/RELEASES.md index b967556e6..7dff26523 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -60,6 +60,9 @@ data can be rebuilt by resync and rollback is an edge case. The skill separately reviews `P2PProtocol`, `BlockProtocol`, and `ABCISemVer`; a software version bump does not update those contracts automatically. `BlockProtocol` is enforced strictly, so bumping it also requires a major. +A `BlockProtocol` change is a full hard fork and a red flag: it needs explicit +confirmation from the release owner for that specific change, even within an +otherwise authorized release. Full-release promotion and stable-to-dev synchronization should preserve ancestry. Master currently has protection rules that must be reconciled with From 4144b6985c5869a5a9e961599fbd52eef38295a5 Mon Sep 17 00:00:00 2001 From: Lukasz Klimek <842586+lklimek@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:29:21 +0000 Subject: [PATCH 3/6] docs(release): keep the versioning policy only in RELEASES.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RELEASES.md is the single source of the versioning rules and protocol counter guidance; the release skill links to it and keeps only the review procedure and its stop-and-ask gates. 🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig --- .agents/skills/tenderdash-release/SKILL.md | 48 +++++----------------- RELEASES.md | 44 ++++++++++++-------- 2 files changed, 39 insertions(+), 53 deletions(-) diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index 0c7e2a069..405adff14 100644 --- a/.agents/skills/tenderdash-release/SKILL.md +++ b/.agents/skills/tenderdash-release/SKILL.md @@ -63,47 +63,21 @@ tree is not a new feature; a patch-equivalent backport may already be released. Explain cherry-picks, merges, existing release bumps, and partial reverts rather than counting them twice. Pure release metadata is not a new compatibility change. -The software version (`TMVersionDefault`) is decided by four versioned contracts: - -| Versioned contract | Evidence and decision | -| --- | --- | -| RPC | Methods, parameters, responses and their semantics | -| ABCI | Application methods, messages, return handling and app coordination; review `ABCISemVer` separately | -| P2P and consensus | Message/channel formats, consensus rules, proposer selection, consensus versions, peer compatibility; review `P2PProtocol` | -| Block format | Serialization, hashes, signing and validity of blocks, votes and commits; review `BlockProtocol` | - -- **Major:** any backward-incompatible change to a versioned contract. This - includes a new consensus version (e.g. `CONSENSUS_VERSION_3`) even when a chain - parameter activates it, any change after which older nodes cannot follow the - network, a removed or semantically changed RPC, and an `ABCISemVer` major. -- **Minor:** a backward-compatible extension of a versioned contract (new optional - fields, RPC methods, or parameters that leave existing networks unchanged). -- **Patch:** fixes that change no versioned contract. A security or consensus fix - is not automatically patch-safe; classify it from its actual contract effect. - -These do not affect the version, but the changelog must describe them with any -operator action: exported Go APIs (not consumed as a library), configuration and -CLI (including removed settings and tightened validation), tooling, CI and docs. -Persisted data is not versioned either: storage changes must migrate -automatically and invisibly to node operators. Data is largely recoverable by -resync and rollback is an edge case, but a change that needs manual migration is -a release blocker, not a version decision. Also record the Dash Platform +Classify the version and each protocol counter (`ABCISemVer`, `P2PProtocol`, +`BlockProtocol`) by the [versioning policy](../../../RELEASES.md#versioning-policy). +Review each versioned contract explicitly (RPC, ABCI, P2P/consensus, block format) +and explain whether each counter must change and why. Do not mechanically +increment every counter or use a major to conceal an unhandled network +compatibility change. List unversioned changes (Go API, configuration, CLI) with +their operator action for the changelog, and record the Dash Platform integration: required Drive/ABCI/Dashmate updates, network activation, mixed-version operation and operator rollout. Internal-only work may need no release; do not manufacture a bump for an analysis request. -Protocol counters and `ABCISemVer` are independent of `TMVersionDefault`: explain -whether each must change, and why. `ABCISemVer` is the ABCI contract's own -SemVer (Drive accepts `^major.minor`), `P2PProtocol` changes with P2P messages or -behavior, and `BlockProtocol` changes only with the block format; nodes enforce it -strictly, so its bump also implies a software major. - -A `BlockProtocol` change is a red flag: it is a full hard fork that invalidates -existing chains for nodes on either side. Never bump it, or prepare a release that -changes it, without the user's explicit confirmation of that specific change; -stop and ask even when a release was otherwise authorized. Do not mechanically increment -every counter, or use a software major to conceal an unhandled network -compatibility change. +**Stop and ask** before bumping `BlockProtocol` or preparing a release that +changes it (full hard fork), even when the release was otherwise authorized, and +when a storage change needs manual migration. + If the diff contains unresolved compatibility questions, report them and defer publication until the Platform/release owner resolves them. diff --git a/RELEASES.md b/RELEASES.md index 7dff26523..bad88e29c 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -38,10 +38,21 @@ an explicit Platform support decision rather than automatic maintenance promises Release tags remain `vX.Y.Z`; prereleases use `vX.Y.Z-dev.N`. The skill evaluates SemVer from compatibility, not branch names or `feat`/`fix` labels. +Full-release promotion and stable-to-dev synchronization should preserve +ancestry. Master currently has protection rules that must be reconciled with +that merge strategy by maintainers before a release. The skill must report any +block and must not bypass or modify branch protections. + ## Versioning policy -The software version is decided only by these contracts: RPC, ABCI, P2P and -consensus, and the block format. +The software version (`TMVersionDefault`) is decided only by these contracts: + +| Contract | Covers | +| --- | --- | +| RPC | Methods, parameters, responses and their semantics | +| ABCI | Application methods, messages, return handling and app coordination | +| P2P and consensus | Message/channel formats, consensus rules and versions, proposer selection, peer compatibility | +| Block format | Serialization, hashes, signing and validity of blocks, votes and commits | - **Major:** a backward-incompatible change to any of them. A new consensus version (for example `CONSENSUS_VERSION_3`) is a major even when a chain @@ -49,25 +60,26 @@ consensus, and the block format. semantically changed RPC, and an `ABCISemVer` major. - **Minor:** a backward-compatible extension, such as new optional fields, RPC methods or parameters that leave existing networks unchanged. -- **Patch:** fixes that change none of these contracts. +- **Patch:** fixes that change none of these contracts. A security or consensus + fix is not automatically patch-safe; classify it by its contract effect. Exported Go APIs, configuration and CLI (including removed settings and tightened validation), tooling, CI and documentation do not affect the version; the changelog describes them and any operator action. Persisted data is not versioned: storage changes must migrate automatically and invisibly to operators, since most -data can be rebuilt by resync and rollback is an edge case. - -The skill separately reviews `P2PProtocol`, `BlockProtocol`, and `ABCISemVer`; a -software version bump does not update those contracts automatically. -`BlockProtocol` is enforced strictly, so bumping it also requires a major. -A `BlockProtocol` change is a full hard fork and a red flag: it needs explicit -confirmation from the release owner for that specific change, even within an -otherwise authorized release. - -Full-release promotion and stable-to-dev synchronization should preserve -ancestry. Master currently has protection rules that must be reconciled with -that merge strategy by maintainers before a release. The skill must report any -block and must not bypass or modify branch protections. +data can be rebuilt by resync and rollback is an edge case. A change that needs a +manual migration blocks the release. + +Protocol counters are reviewed separately; a software version bump does not +update them automatically: + +- `ABCISemVer` is the ABCI contract's own SemVer. Drive (rs-tenderdash-abci) + accepts `^major.minor` of its linked version. +- `P2PProtocol` changes with P2P messages or behavior. +- `BlockProtocol` changes only with the block format. Nodes enforce it strictly, + so its bump also requires a major. It is a full hard fork and a red flag: it + needs explicit confirmation from the release owner for that specific change, + even within an otherwise authorized release. ## Validation and artifacts From 3572406eecb2a03d97094320743416a494779e4a Mon Sep 17 00:00:00 2001 From: Lukasz Klimek <842586+lklimek@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:30:25 +0000 Subject: [PATCH 4/6] docs(release): link release rules from the skill instead of repeating them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Branch/source roles, promotion and protection rules, artifact contents and Docker tag/alias rules live in RELEASES.md; the skill keeps the procedure, commands, verification steps and stop conditions. 🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig --- .agents/skills/tenderdash-release/SKILL.md | 59 ++++++++++------------ 1 file changed, 26 insertions(+), 33 deletions(-) diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index 405adff14..d7ccfe6f1 100644 --- a/.agents/skills/tenderdash-release/SKILL.md +++ b/.agents/skills/tenderdash-release/SKILL.md @@ -18,21 +18,21 @@ or publish embargoed fixes without the coordinated disclosure authorization. ## Establish the release context Resolve the intended Dash Platform version/network and operation: next release, -prerelease, or stable hotfix. Inspect live refs, published tags/releases, and open -release PRs before selecting commits. Fetch the necessary refs/tags; do not trust -stale local tracking refs or assume the GitHub default is the release source. +prerelease, or stable hotfix; release sources are defined in +[RELEASES.md](../../../RELEASES.md#branches-and-release-sources). Inspect live +refs, published tags/releases, and open release PRs before selecting commits. +Fetch the necessary refs/tags; do not trust stale local tracking refs or assume +the GitHub default is the release source. - **Next release:** use `origin/dev` and record its exact SHA. Freeze that candidate; a later tip is a new candidate requiring review. The helper accepts that reviewed ancestor of the fetched integration tip without substituting newer commits. A temporary release branch can isolate a freeze. - **Current-stable hotfix:** start from `origin/master` and its latest published - tag. Isolate only required fixes in a feature branch; exclude next-version - development. Plan the forward-port to dev as part of completion. -- **Another deployed Platform line:** require an explicit supported-deployment - decision and start from that line's last released tag, not master or dev. - This is an exceptional manual path: the helper intentionally validates only - next releases and current-stable hotfixes. Do not weaken it to admit another line. + tag in a feature branch. Plan the forward-port to dev as part of completion. +- **Another deployed Platform line:** stop until the supported-deployment + decision is explicit. The helper validates only the two modes above; do not + weaken it to admit another line. Choose the latest **published stable tag reachable from the candidate** for the compatibility baseline. Verify its commit and GitHub release are the intended @@ -105,13 +105,11 @@ anything not verified. Signed binary building does not prove consensus or upgrad compatibility. Fill every applicable repository PR-template section with the compatibility rationale and validation, including AI attribution. -A prerelease preparation PR targets the integration branch; a full-release PR -promotes the frozen candidate to master and preserves ancestry under the agreed -release merge strategy. A stable patch PR targets master. Respect protections: -master's current linear-history rule conflicts with the documented promotion -merge, so publication must wait for maintainers to reconcile that policy; never -use an automatic administrative bypass. Stop after the requested preparation or -PR phase if no release publication was requested. +A prerelease preparation PR targets `dev`, a full-release PR promotes the frozen +candidate to `master`, and a stable patch PR targets `master`. Follow the +promotion and branch-protection rules in [RELEASES.md](../../../RELEASES.md#branches-and-release-sources); +report a protection conflict instead of bypassing it. Stop after the requested +preparation or PR phase if no release publication was requested. ## Finalize an explicitly requested release @@ -135,23 +133,18 @@ When signed binaries are required, run from a checkout with that exact tag: bash scripts/release/build-artifacts.sh REPO TAG REVIEWED_MERGE_SHA OUTPUT_DIRECTORY ``` -The helper builds Linux amd64/arm64, signs each binary with GPG (optional -`GPG_KEY_ID`), verifies signatures, and produces tarballs, `SHA256SUMS`, and -`SOURCE_COMMIT`. It clones the reviewed source, never changes the caller's branch, -and never uploads. Use a fresh output directory under the user's artifact root. -Retain provenance and verify checksums/signatures before uploading to the matching -draft. Compare existing assets rather than overwriting them with `--clobber`. -For unsigned/dev releases, state explicitly which binary artifacts are omitted; -Docker publication remains separate. - -Publishing the draft triggers `.github/workflows/docker.yml`. Check that the -Platform rollout and release request authorize this publication. Verify exact source -SHA, binary version and image labels. Stable alias promotion is serialized and -requires the current latest stable release with no higher stable tag. Prereleases, -manual runs and older-line releases must not replace stable aliases. Historical -source without explicit Docker VERSION support needs a separately reviewed path. -After publication, verify the remote tag SHA, release assets, Docker image tags -and digests. If asynchronous publishing fails, report the partial state and resume +See [RELEASES.md](../../../RELEASES.md#validation-and-artifacts) for what it +produces; set `GPG_KEY_ID` to choose the key. Use a fresh output directory under +the user's artifact root, keep provenance, and verify checksums/signatures before +uploading to the matching draft. Compare existing assets rather than overwriting +them with `--clobber`. When no binaries are built, state which artifacts are +omitted in the release notes. + +Publishing the draft triggers `.github/workflows/docker.yml` (tag and alias rules +in [RELEASES.md](../../../RELEASES.md#validation-and-artifacts)). Check that the +Platform rollout and release request authorize this publication. After +publication, verify the remote tag SHA, release assets, image tags, labels, +digests and binary version, and that no stable alias moved unexpectedly. If asynchronous publishing fails, report the partial state and resume only the missing step; do not move tags or repeat a completed release blindly. Forward-port stable fixes and release metadata to dev with a reviewed merge or From 95eb2d75d4da5e6b15ce432c7110593ff273eaed Mon Sep 17 00:00:00 2001 From: Lukasz Klimek <842586+lklimek@users.noreply.github.com> Date: Mon, 9 Nov 2026 21:08:59 +0000 Subject: [PATCH 5/6] docs(release): add release verification steps learned from 2.0.0-dev.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Check ABCISemVer changes against the rs-tenderdash-abci caret rule and prepare its PR before tagging. - Require an empty diff between the reviewed head and the merge commit, and generate release notes from the merged changelog. - Look up drafts by tag name. - Record stable Docker alias digests before publishing. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig 🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent --- .agents/skills/tenderdash-release/SKILL.md | 23 ++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index d7ccfe6f1..63a786f36 100644 --- a/.agents/skills/tenderdash-release/SKILL.md +++ b/.agents/skills/tenderdash-release/SKILL.md @@ -74,6 +74,12 @@ integration: required Drive/ABCI/Dashmate updates, network activation, mixed-version operation and operator rollout. Internal-only work may need no release; do not manufacture a bump for an analysis request. +When `ABCISemVer` changes, check it against the `check_version` caret rule +(`^major.minor`) in `dashpay/rs-tenderdash-abci`: which existing apps still +accept the new Tenderdash, and which Tenderdash versions apps built on the new +crate reject. Prepare the matching rs-tenderdash-abci PR (proto default version) +before tagging; its CI passes only once the tag and Docker image exist. + **Stop and ask** before bumping `BlockProtocol` or preparing a release that changes it (full hard fork), even when the release was otherwise authorized, and when a storage change needs manual migration. @@ -114,8 +120,11 @@ preparation or PR phase if no release publication was requested. ## Finalize an explicitly requested release Verify the release PR is merged, identify its exact merge SHA, and inspect the -resulting tree/version/changelog against the reviewed candidate. Include any -merge-time differences in validation. Do not use a moving `master`/`dev` tip as +resulting tree/version/changelog against the reviewed candidate: +`git diff REVIEWED_HEAD MERGE_SHA` should be empty. Include any merge-time +differences in validation. Generate the release notes from the version's +section of `CHANGELOG.md` in the merged tree, plus a note on release artifacts +(Docker image, binaries or their absence, tag signing). Do not use a moving `master`/`dev` tip as the tag target. Recheck remote tags and release drafts before acting. For a new version, create the release tag explicitly at that reviewed merge SHA @@ -125,7 +134,9 @@ compare its peeled commit to the reviewed SHA and reuse it only on an exact match; a mismatch stops the release. Never force-update or delete a release tag. Create a draft GitHub release with `gh release create TAG --verify-tag --draft --notes-file NOTES` (add `--prerelease` for `-dev.N`). Existing drafts must match -the same tag/SHA; inspect and reuse rather than deleting/recreating them. +the same tag/SHA; inspect and reuse rather than deleting/recreating them. Look +drafts up by tag name: a draft's URL shows `untagged-…`, and its +`targetCommitish` (the default branch) is irrelevant once the tag exists. When signed binaries are required, run from a checkout with that exact tag: @@ -142,7 +153,11 @@ omitted in the release notes. Publishing the draft triggers `.github/workflows/docker.yml` (tag and alias rules in [RELEASES.md](../../../RELEASES.md#validation-and-artifacts)). Check that the -Platform rollout and release request authorize this publication. After +Platform rollout and release request authorize this publication. Before +publishing, record the digests of the stable aliases (`latest`, `X`, `X.Y`) and +the current stable version tag, e.g. with +`docker buildx imagetools inspect dashpay/tenderdash:TAG --format '{{.Manifest.Digest}}'`, +so you can compare them afterwards. After publication, verify the remote tag SHA, release assets, image tags, labels, digests and binary version, and that no stable alias moved unexpectedly. If asynchronous publishing fails, report the partial state and resume only the missing step; do not move tags or repeat a completed release blindly. From 575b911b89a4273cf8591a962d1eaaf742acdc6b Mon Sep 17 00:00:00 2001 From: Lukasz Klimek <842586+lklimek@users.noreply.github.com> Date: Tue, 10 Nov 2026 07:25:38 +0000 Subject: [PATCH 6/6] docs(release): cover rs-tenderdash-abci release and deployed Platform checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - After the Tenderdash release, rerun the rs-tenderdash-abci PR CI, merge, tag the same version on develop and publish a GitHub release; the PR already carries the version bump. - Check the deployed Platform release: Drive's tenderdash-abci ABCI range, dashmate's pinned Tenderdash image, and dashmate's default Tenderdash configuration against new validation. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig 🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent --- .agents/skills/tenderdash-release/SKILL.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index 63a786f36..c5b17167a 100644 --- a/.agents/skills/tenderdash-release/SKILL.md +++ b/.agents/skills/tenderdash-release/SKILL.md @@ -71,14 +71,21 @@ increment every counter or use a major to conceal an unhandled network compatibility change. List unversioned changes (Go API, configuration, CLI) with their operator action for the changelog, and record the Dash Platform integration: required Drive/ABCI/Dashmate updates, network activation, -mixed-version operation and operator rollout. Internal-only work may need no -release; do not manufacture a bump for an analysis request. +mixed-version operation and operator rollout. Check against the deployed +Platform release: the ABCI range accepted by Drive's pinned `tenderdash-abci` +tag, the Tenderdash image dashmate pins, and whether dashmate's default +Tenderdash configuration passes any new configuration validation. Internal-only +work may need no release; do not manufacture a bump for an analysis request. When `ABCISemVer` changes, check it against the `check_version` caret rule (`^major.minor`) in `dashpay/rs-tenderdash-abci`: which existing apps still accept the new Tenderdash, and which Tenderdash versions apps built on the new -crate reject. Prepare the matching rs-tenderdash-abci PR (proto default version) -before tagging; its CI passes only once the tag and Docker image exist. +crate reject. Prepare the matching rs-tenderdash-abci PR before tagging. It +carries the crate version, proto default version and changelog, so no separate +version PR is needed. Its CI passes only once the Tenderdash tag and Docker +image exist: after publication, rerun it, then tag the same version on the +merge commit in `develop` and publish a GitHub release (a prerelease for +`-dev.N`). Drive links the crate by that tag. **Stop and ask** before bumping `BlockProtocol` or preparing a release that changes it (full hard fork), even when the release was otherwise authorized, and