Skip to content

docs(release): Beta channel procedure: branch, version, changelog, tag, promote, roll back #1496

Closed

Description

@ZhuchkaTriplesix

Part of the Beta channel epic #1499.

Problem

The release process documents only stable releases. The beta path has several traps that are easy to miss:

  • scripts/extract-changelog-section.sh needs a section ## [0.5.0-beta.1] (the Publish GitHub Release job fails otherwise);
  • .github/workflows/version-bump.yml runs when a PR into main is closed and drops any -prerelease from pubspec.yaml, so a beta version only exists on the release branch and the tag has to be set by hand;
  • the tag and the pubspec semver must match (version-hint warns only);
  • the CHANGELOG of a beta is a delta, the final release repeats everything.

Scope

  • docs/tags-and-releases.md: a Beta channel section: branch release/X.Y.Z, version: X.Y.Z-beta.N+B in pubspec, ## [X.Y.Z-beta.N] in CHANGELOG, the annotated tag, what the workflow does, what Stable users see (nothing) and Beta users see (an update).
  • Promote: pubspec X.Y.Z, ## [X.Y.Z] with the full notes, tag X.Y.Z (the beta tags stay).
  • Roll back: mark the bad stable release as pre-release (or delete it) so releases/latest returns the previous one; the AUR / APT / DNF side needs its own revert (describe).
  • docs/release-checklist.md: a beta checklist (smoke subset, how long a beta must be out, blockers) and the promote step; update the Versioning part that now says 0.4.x.
  • CONTRIBUTING.md: link.
  • Russian summary in docs/tags-and-releases.md follows the file's language.

Acceptance

  • Following the document step by step produces a beta pre-release and then a stable one on a fork.
  • The traps above are each named with the symptom and the fix.

Activity

  1. added
    documentationImprovements or additions to documentation
    P2Medium priority / Parity & Refactoring
    on Oct 11, 2026
  2. ZhuchkaTriplesix commented on Oct 25, 2026

    @ZhuchkaTriplesix
    MemberAuthor

    Done on dev in #1707, #1711 (merged). Closing by hand: the PRs target dev, so GitHub would only close this when dev is merged into main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium priority / Parity & RefactoringdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions