diff --git a/.agents/skills/tenderdash-release/SKILL.md b/.agents/skills/tenderdash-release/SKILL.md index faadfd06c..c5b17167a 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 @@ -63,27 +63,34 @@ 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: - -| Contract | Evidence and decision | -| --- | --- | -| Exported non-internal Go API and RPC | Removed/changed types, methods, fields, response semantics, caller migration | -| 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. - -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. +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. 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 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 +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. @@ -111,19 +118,20 @@ 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 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 @@ -133,7 +141,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: @@ -141,23 +151,22 @@ 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. 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. Forward-port stable fixes and release metadata to dev with a reviewed merge or 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..bad88e29c 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -36,15 +36,51 @@ 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. 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 (`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 + 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. 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. 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 Record baseline tag/SHA, source SHA, release version, protocol decisions,