ScuroNeko/Laniakea
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Releases 27 Wiki Activity
REPOSITORY / ScuroNeko/Laniakea

Wiki

KNOWLEDGE REPOSITORY
Page: Semver and Releases
Pages
AGENTS Auto Generated Commands RU Auto Generated Commands Bot Lifecycle RU Bot Lifecycle Bot Options and Configuration RU Bot Options and Configuration Commands and Plugins RU Commands and Plugins Drafts RU Drafts Error Handling RU Error Handling Framework Backlog RU Framework Backlog Getting Started RU Getting Started Home RU Home Inline Keyboards and Payloads RU Inline Keyboards and Payloads Localization RU Localization Logging RU Logging MessageContext RU MessageContext Middleware RU Middleware Migration RU Migration Policies RU Policies Rate Limiting RU Rate Limiting Recipes RU Recipes Rich Messages RU Rich Messages Runners RU Runners Scenes RU Scenes Semver and Releases RU Semver and Releases Sentry Integration RU Sentry Integration Testing Bots with Laniakea RU Testing Bots with Laniakea Update Routing Model RU Update Routing Model V2 Migration Plan RU V2 Migration Plan Webhook Runtime RU Webhook Runtime tgapi Overview RU tgapi Overview
Clone
5
Semver and Releases
ScuroNeko edited this page 2026-05-20 13:22:27 +03:00
Table of Contents

Semver and Releases

Russian version: Semver-and-Releases-RU

This page is for maintainers and contributors who need the project's release rules in one place. It complements SEMVER.md, the changelog, and the repository workflow rules in AGENTS.md.

Sources of truth

For release and compatibility work, keep these files aligned:

  • SEMVER.md for the project's semantic-versioning policy;
  • CHANGELOG.md for user-visible changes grouped by target version;
  • utils/version.go for the version constants currently declared in code;
  • AGENTS.md for repository workflow rules around changelog updates and breaking changes.

What counts as public API

The public API includes:

  • exported identifiers in package laniakea;
  • exported identifiers in package tgapi;
  • documented behavior in README.md, README_RU.md, and package godoc.

That means compatibility is not only about function names. Behavioral guarantees documented for callers also count.

Examples of public API surface:

  • handler signatures;
  • exported helper methods such as AnswerLong(...);
  • exported request and response DTOs in tgapi;
  • callback payload behavior when documented as stable.

What is a breaking change

A change requires a major version bump when it breaks existing callers or documented expectations.

Typical breaking changes include:

  • renaming or removing exported identifiers;
  • changing exported function or method signatures;
  • changing struct field names or JSON wire compatibility in tgapi;
  • changing documented behavior in a way that breaks existing bots.

Examples from the current release-candidate history:

  • changing CommandExecutor to return error;
  • changing NewBot(...) to return (*Bot[T], error);
  • renaming BaseMenuButton to MenuButton;
  • changing shutdown methods such as Bot.Close(ctx) to Bot.Close().

How version numbers are chosen

The project follows semantic versioning with prerelease builds.

In broad terms:

  • major version: required for breaking public API changes;
  • minor version: backward-compatible additions;
  • patch version: backward-compatible fixes and clarifications;
  • -rc.N: prerelease iteration before the stable release line.

The current code declares its version in utils/version.go:

  • VersionString
  • VersionMajor
  • VersionMinor
  • VersionPatch
  • VersionBeta

Release candidates

The project is currently in the 1.0.0-rc.N phase.

This means:

  • API adjustments can still happen before v1.0.0;
  • changelog sections should still be written carefully and explicitly;
  • once v1.0.0 is released, breaking changes should require a new major version under the documented policy.

Even during RCs, treating compatibility seriously is still useful because users may already be building real bots against these versions.

Changelog mapping

Each user-visible code or documentation change in the main repository should be recorded in CHANGELOG.md under the next target version section.

Repository rules currently require:

  • changes in the main repository update CHANGELOG.md;
  • wiki-only changes in .wiki/ do not require main changelog updates;
  • changelog entries must go into the section for the next version after the latest published tag;
  • the target changelog version must match utils/version.go.

This keeps three things synchronized:

  • the last published version in git tags;
  • the declared next version in CHANGELOG.md;
  • the version constants in code.

Latest published tag versus next version

The repository workflow distinguishes between:

  • the latest published git tag;
  • the next unreleased version section in CHANGELOG.md;
  • the version currently declared in utils/version.go.

The intended rule is:

  • if the latest published tag is vX.Y.Z, new work should land in the next version section, not the already published one;
  • utils/version.go should declare that same unreleased target version.

If these drift apart, the version story becomes ambiguous for users and maintainers.

Breaking-change policy during normal development

Repository workflow currently forbids unapproved breaking changes unless the target version is a new major version.

In practice, when a breaking change is requested, the preferred options are:

  1. avoid the breaking change;
  2. add a backward-compatible alternative;
  3. bump the major version first, then make the break.

This is especially relevant for:

  • handler signatures;
  • bot and plugin lifecycle APIs;
  • tgapi DTO and wire-format compatibility;
  • callback payload defaults and semantics.

What usually belongs in a changelog entry

Good changelog entries describe user-visible effects such as:

  • new helpers or methods;
  • fixed runtime behavior;
  • changed defaults;
  • renamed or removed APIs;
  • newly enforced validation or decoding behavior.

Low-level internal refactors without user-visible effects usually do not need prominent changelog language unless they affect documented guarantees.

Maintainer checklist before release-related edits

Before editing version or changelog data:

  1. inspect the latest published git tag;
  2. inspect the target section in CHANGELOG.md;
  3. inspect utils/version.go;
  4. decide whether the change is additive, fixing, or breaking;
  5. confirm that the chosen version level matches that impact.

Related pages

  • Migration for upgrade guidance across release candidates
  • Bot-Lifecycle for runtime and single-use guarantees

Navigation

Start here

Runtime and Architecture

Interaction and Telegram API

Practical Guides

Maintenance