Skip to content

docs(release): version by RPC, ABCI, P2P/consensus and block contracts - #1603

Merged
lklimek merged 7 commits into
devfrom
docs/release-semver-policy
Nov 10, 2026
Merged

lklimek merged 7 commits into
devfrom
docs/release-semver-policy

Conversation

@Claudius-Maginificent

@Claudius-Maginificent Claudius-Maginificent commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR: Tenderdash version numbers follow what node operators and Dash Platform depend on: RPC, ABCI, P2P/consensus and the block format. A new consensus version is always a major release.

User story

As a node operator, I want a major version to mean that I must upgrade to keep following the network, to plan upgrades from the version number alone.

Scenario

Base flow

A maintainer prepares a release and picks its version with the tenderdash-release skill.

Actual behavior

The policy treats the exported Go API, configuration, CLI and storage like network contracts. As a result:

  • A Go interface change forces a major, although no Platform component uses Tenderdash as a Go library.
  • A new consensus version that a chain parameter activates can be classified as a minor.

Expected behavior

  • Only backward-incompatible changes to RPC, ABCI, P2P/consensus or the block format make a major. A new consensus version counts as one, even when a parameter activates it.
  • Go API, configuration and CLI changes do not affect the version, but the changelog still documents them.
  • Storage changes must migrate automatically.

Detailed discussion

What was done

  • RELEASES.md is the single source of release rules. Its new "Versioning policy" section contains:

    • a table of the four versioned contracts;
    • major, minor and patch rules, including that a consensus version is a major;
    • Go API, configuration, CLI, tooling and docs as unversioned but documented in the changelog;
    • the storage rule: storage must migrate automatically, and a manual migration blocks the release;
    • guidance for each protocol counter. A BlockProtocol bump implies a major and, as a full hard fork, requires explicit confirmation of that specific change.
  • .agents/skills/tenderdash-release/SKILL.md keeps only the procedure:

    • evidence collection, the review steps, commands and verification;
    • the stop-and-ask gates: BlockProtocol, manual storage migration, another deployed line.

    For rules it links to RELEASES.md: versioning policy, branches and release sources, promotion and protections, artifact contents, and Docker tags and aliases.

  • The skill also adds verification steps that came out of releasing v2.0.0-dev.1:

    • check an ABCISemVer change against the rs-tenderdash-abci check_version 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 draft releases by tag name;
    • record stable Docker alias digests before publishing;
    • after publication, finish the rs-tenderdash-abci release: rerun its CI, merge, tag the same version on develop and publish a GitHub release;
    • check the deployed Platform release: Drive's tenderdash-abci ABCI range, the Tenderdash image dashmate pins, and dashmate's default Tenderdash configuration against new validation.
  • README.md: the SemVer summary is updated to match.

  • CONTRIBUTING.md: links to the policy.

Testing

  • python3 -B -m unittest discover -s scripts/release -p test_release.py: OK
  • sh scripts/test-local-gates.sh: passed
  • markdownlint-cli@0.45.0 --config .markdownlint.yml on the edited files: clean

Breaking changes

None. This changes only documentation and process. Under this policy, v2.0.0-dev.1 (#1602) is still a major because it adds CONSENSUS_VERSION_2 and changes broadcast_tx RPC behavior.

Prior work

Attribution

Prepared with Claude Code (Claude Opus 5.5).

🤖 Generated with Claude Code

https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig

🤖 Co-authored by Claudius the Magnificent AI Agent

PR Hygiene · 575b911

  • Bots — thepastaclaw ✓
  • Self-review — not asked of a bot author
  • Build green
  • Approvals
    • files with no dedicated owner (.agents/skills/tenderdash-release/SKILL.md, CONTRIBUTING.md, README.md and 1 more) — approved by lklimek

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

lklimek and others added 2 commits November 9, 2026 16:25
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.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig
A BlockProtocol change is a full hard fork; the release skill must stop
and get explicit confirmation of that specific change.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig
@coderabbitai

coderabbitai Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

lklimek and others added 2 commits November 9, 2026 16:29
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.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig
… them

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.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig
@thepastaclaw

thepastaclaw commented Nov 9, 2026 •

Copy link
Copy Markdown

✅ Final review complete — Phase 1 only — no blockers (commit 575b911) · triage: trivial

lklimek added a commit that referenced this pull request Nov 9, 2026
* chore(release): prepare 2.0.0-dev.1

Bump TMVersionDefault to 2.0.0-dev.1, ABCISemVer to 1.5.0 and
P2PProtocol to 11; BlockProtocol stays 14. Add the 2.0.0-dev.1
changelog section reviewed against v1.8.2..0e08aa0.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig

* docs(changelog): separate breaking changes from migration notes

List consensus and RPC incompatibilities under Breaking Changes and move
Go API, configuration and CLI changes to Migration Notes, per the
versioning policy proposed in #1603. Add the broadcast_evidence change
from #1547.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig

---------

Co-authored-by: Lukasz Klimek <842586+lklimek@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>
@lklimek
lklimek marked this pull request as ready for review November 9, 2026 21:57
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 9, 2026

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Final review — Phase 1 only (trivial change)

Verified the documentation changes at 8ba22c2 and found no actionable issue in the supplied finding. The README summarizes the release policy rather than claiming that the node contains a universal migration mechanism. Current build, test, lint, and release-tooling checks pass; PastaClaw review and PR Hygiene remain pending.

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-gate-verifier, role: final-verifier)

  • Triage: trivial by gpt-6.1-sol (effort low) — The diff changes only release-policy documentation and procedural guidance, with no executable behavior or protocol changes.
  • Phase 1 reviewers: glm-5.3-flash — general (completed, effort high); agent phase1-reviewer
  • Phase 1 model: glm-5.3-flash — zai quota: 5h 70% left, weekly 94% left; passed over gemini-3.8-flash-high (antigravity quota lookup failed)
  • Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-gate-verifier
  • Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves

@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown

Policy satisfied — this can merge.
Full checklist in the description.

@github-actions github-actions Bot removed the waiting-bots Waiting for the review bots to report on this head label Nov 9, 2026
… checks

- 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WunYYgcoPDNh3uebhUCwig

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review — Final review — Phase 1 only (trivial change)

The documentation-only changes consistently define versioning around RPC, ABCI, P2P/consensus, and block-format contracts, while preserving the release procedure and required safety gates. The changed links, policy details, and cross-repository verification guidance are coherent with the repository structure and existing release tooling; CI shows no failed code checks attributable to this change, with only review-hygiene checks still pending.

🔴 0 blocking | 🟡 0 suggestion(s) | 💬 0 nitpick(s)

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-gate-verifier, role: final-verifier)

  • Triage: trivial by gpt-6.1-sol (effort low) — This is a documentation and release-process change with no production behavior, consensus logic, storage migration, or other runtime impact.
  • Phase 1 reviewers: glm-5.3-flash — general (completed, effort high); agent phase1-reviewer
  • Phase 1 model: glm-5.3-flash — zai quota: 5h 95% left, weekly 92% left; passed over gemini-3.8-flash-high (antigravity quota lookup failed)
  • Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-gate-verifier
  • Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review. Verify the current code and confirm that no unresolved issues remain.

No unresolved findings remain from the prior review on this head.

@github-actions

Copy link
Copy Markdown

Ready for review — files with no dedicated owner: lklimek or shumkov.
Full checklist in the description.

@github-actions github-actions Bot added ready-for-human PR Hygiene: bots done, author self-reviewed, awaiting human review and removed waiting-bots Waiting for the review bots to report on this head labels Nov 10, 2026
@github-actions
github-actions Bot requested review from lklimek and shumkov November 10, 2026 09:06
@lklimek
lklimek enabled auto-merge (squash) November 10, 2026 10:03
@github-actions

Copy link
Copy Markdown

Policy satisfied — this can merge.
Full checklist in the description.

@github-actions github-actions Bot removed the ready-for-human PR Hygiene: bots done, author self-reviewed, awaiting human review label Nov 10, 2026
@lklimek
lklimek merged commit 27c63a9 into dev Nov 10, 2026
29 checks passed
@lklimek
lklimek deleted the docs/release-semver-policy branch November 10, 2026 10:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants