Eino: Release Notes & Migration Guide

Version Management Guidelines

Go SDK projects typically follow Semantic Versioning (Semver) conventions. A Semver version number consists of three parts in the format:

πŸ’‘ v{MAJOR}.{MINOR}.{PATCH}

  • MAJOR: Major version number, indicates significant updates or incompatible API changes.
  • MINOR: Minor version number, indicates new features added while maintaining backward compatibility.
  • PATCH: Patch number, indicates backward-compatible bug fixes.

Additionally, Semantic Versioning supports pre-release versions and metadata tags for marking pre-release, experimental, and other unofficial versions. The format is:

πŸ’‘ v{MAJOR}.{MINOR}.{PATCH}-{PRERELEASE}+{BUILD}

  • PRERELEASE: Pre-release version identifier, such as alpha, beta, rc (Release Candidate).
  • BUILD: Build metadata (optional), typically used to identify specific builds, such as CI build numbers.

Eino follows the semantic versioning specification above and will have the following version types:

Version TypeVersion Number FormatVersion DescriptionNotes
Stable ReleaseFormat:
  • v{MAJOR}.{MINOR}.{PATCH}
    • Examples:
  • v0.1.1
  • v1.2.3
  • When releasing stable versions, ensure API stability and backward compatibility.
  • Strictly follow semantic versioning: only increment the MAJOR version for significant incompatible changes, increment MINOR for new features, and increment PATCH for bug fixes only.
  • Ensure comprehensive unit tests, integration tests, and performance tests before release.
  • Provide detailed Release Notes upon release, listing important changes, fixes, features, and migration guides (if any).
    • Pre-release
  • Alpha
  • Beta
  • RC (Release Candidate)
    		• Format:
  • v{MAJOR}.{MINOR}.{PATCH}-{alpha/beta/rc}.{num}
    • Examples:
  • v0.1.1-beta.1
  • v1.2.3-rc.1
  • v1.2.3-rc.2
  • Alpha: Internal test version, features may not be complete, may have many bugs, not recommended for production environments.
  • Beta: Features are mostly complete but may still have bugs, suitable for public testing, not recommended for production environments.
  • RC (Release Candidate): Release candidate, features complete and generally stable, recommended for final comprehensive testing. If no critical bugs exist, the RC version will become the stable version. Generally, the last RC version will become the stable version.
    • Canary/Experimental/DevFormat:
  • v{MAJOR}.{MINOR}.{PATCH}-{dev}.{num}
    • Examples:
  • v0.1.1-dev.1
  • v1.2.3-dev.2
  • Canary versions are highly unstable, typically used for testing early implementations of new features or architectures. These versions may contain experimental features that could be removed or significantly modified in the future.
  • Canary versions are generally developed on experimental branches
    		• Generally not used internally at ByteDance, may be used in the open source community

    Common Understanding About V0, V1, Vn (n>1)

    TitleDescriptionNotes
    Instability Within V0 Major Versions
  • v0.x.x indicates the library is still in an unstable state, may introduce incompatible changes during MINOR version iterations, API may change, no backward compatibility is guaranteed.
  • Users should expect API changes when using these versions
  • Version number increments will not strictly follow semantic versioning rules
  • The design goal of v0.x.x is rapid iteration, allowing developers to release library versions while the API is unstable and collect user feedback.
    • Stability Within V1, Vn (n>1) Major Versions
  • v1.0.0 indicates the library has reached a stable state, API design is mature, backward compatibility is guaranteed, meaning future 
    v1.x.x
    versions will not introduce incompatible changes.
  • Strictly follows semantic versioning
  • Incompatible API changes will require a MAJOR version increment to release. For example, the version would need to be bumped to 
    v2.0.0
    .
  • Backward compatible feature updates will be released through MINOR version increments, e.g., 
    v1.1.0
    .
  • Backward compatible bug fixes will be released through PATCH version increments, e.g., 
    v1.0.1
    .

    • πŸ’‘ Currently, since Eino is being released for the first time, although Eino’s API is initially stable, it has not been validated at large scale in production. The MAJOR version is temporarily set to V0. After validation by at least 50+ business lines, the version will be upgraded to V1.

    Release Notes Document Structure

    • Each {MAJOR}.{MINOR} minor version has its own document
      • Naming format: “Eino: v1.2.* {title description}”
    • The {MAJOR}.{MINOR} minor version records all ChangeLogs for that version
    • In subdirectories of minor versions, detailed descriptions of each PATCH can optionally be placed
    .
β”œβ”€β”€ v1.0.*
β”‚   └── bug_fix_1_x.txt
β”œβ”€β”€ v0.2.*
β”œβ”€β”€ v0.1.*
    β”œβ”€β”€ bug_fix_1_xxx.txt
    β”œβ”€β”€ bug_fix_2_xxxxx.txt
    └── bug_fix_3_xxxxxxx.txt
    Eino: v0.1.*-first release

    Eino: v0.2.*-second release

    Eino: v0.3.*-tiny break change

    Eino: v0.4.*-compose optimization

    Eino: v0.5.*-ADK implementation

    Eino: v0.6.*-jsonschema optimization

    Eino: v0.7.*-interrupt resume refactor

    Eino: v0.8.*-adk middlewares


    Last modified March 2, 2026: feat: sync eino docs (#1512) (96139d4140)