Release Lifecycle & LTS

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/create-sync-pr.sh
• source/lib/librdkafka-2.10.1/packaging/RELEASE.md
• source/lib/rocksdb/unreleased_history/README.txt
• source/lib/rocksdb/unreleased_history/release.sh
• source/lib/librdkafka-2.10.1/CONTRIBUTING.md

FluentDo Agent provides a hardened, stable, and secure downstream distribution of Fluent Bit, featuring predictable releases and long-term supported (LTS) versions for 24 months. This document outlines the versioning scheme, release schedule, support lifecycle, and the processes involved in creating and managing releases. The lifecycle is designed to provide reliability and predictability for production deployments.

The release process involves several key stages, including synchronization with the upstream Fluent Bit repository, a structured approach to managing release notes, and a phased release-candidate-to-final-release workflow.

Versioning and Release Schedule

FluentDo Agent uses a date-based format for its main releases and transitions to a semantic versioning-like format for LTS releases. This approach provides clarity on the age and support status of a version.

Sources: README.md:27-36

Versioning Scheme

• Main Releases: Follow a Year.Month.Week format (e.g., 25.07).
• LTS Releases: Once a main release is designated as LTS, it maintains its major and minor version, with only the patch version incrementing for subsequent updates (e.g., 25.10.1, 25.10.2).

Sources: README.md:34-36

Release Types and Frequency

The project follows a regular cadence for different types of releases to ensure timely updates, security patches, and long-term stability.

Release Type	Frequency	Description
LTS Release	Twice yearly (April, Oct)	Long-term support for 24 months
Regular Release	Quarterly	6-month support cycle
Security Updates	Weekly	CVE patches and critical fixes
Patch Release	As needed	Bug fixes and minor updates
Main Builds	Weekly	Latest development builds from main branch

Sources: README.md:40-47

Version Support Matrix

The support matrix provides a clear overview of the status and support window for each version.

Version	Release Date	Type	End of Support	Status	Branch
26.10	Oct 2026	LTS	Oct 2028	🟡 Planned
26.04	Apr 2026	LTS	Apr 2028	🟢 Active	main
25.10	Oct 2025	LTS	Oct 2027	🟢 Active	release/25.10-lts
25.07	Jul 2025	Regular	Jan 2026	🟢 Active

Sources: README.md:27-33

Release Process

The release process is a multi-stage workflow that includes upstream synchronization, release note management, and a formal release candidate (RC) cycle.

Upstream Synchronization

As a downstream distribution of Fluent Bit, FluentDo Agent regularly syncs with the upstream repository. This process is managed using the create-sync-pr.sh script.

The following diagram illustrates the upstream sync workflow automated by the script.

The script automates the creation of a pull request for upstream syncs. Key steps include:

1. Prerequisite Checks: Verifies that gh (GitHub CLI) is installed and authenticated, and the working directory is clean.
2. Commit Collection: Gathers all [upstream] commits since the last sync with origin/main. It categorizes them into "Technical Fixes & Improvements", "Test Updates", and "Other Changes".
3. PR Body Generation: Creates a detailed PR body from a template, including the categorized commit lists, links to the upstream commit range, and a verification checklist.
4. Branch Management: Creates a new branch (e.g., sync/fluent-bit-vX.Y.Z) or updates an existing one.
5. PR Creation: Submits the PR to GitHub, optionally as a draft and with auto-merge enabled.

Sources: scripts/create-sync-pr.sh:111-285

Release Note and Changelog Management

To avoid merge conflicts and keep changelogs organized, release notes are not added directly to a central HISTORY.md or CHANGELOG.md file. Instead, individual markdown files are created for each noteworthy change. A script later consolidates these notes during the release process. This practice is adopted from dependencies like RocksDB.

The diagram below shows the flow for adding and releasing notes.

Adding Release Notes

Developers add a new file for each change into a categorized directory. The unreleased_history/add.sh script can be used to facilitate this.

• Categories:
  • new_features
  • behavior_changes
  • public_api_changes
  • bug_fixes
  • performance_improvements
• File Naming: The file name determines the sort order within a category. Important entries can be prefixed with a number (e.g., 100_important_fix.md).

Sources: source/lib/rocksdb/unreleased_history/README.txt:4-10, source/lib/rocksdb/unreleased_history/release.sh:53-58

Generating the HISTORY.md

The unreleased_history/release.sh script automates the update of HISTORY.md:

1. It reads the current version from include/rocksdb/version.h.
2. It creates a new version header in HISTORY.new.
3. It iterates through the category directories in a hard-coded order.
4. For each note file, it formats the content (e.g., adds a * prefix) and appends it to HISTORY.new.
5. It removes the processed note files using git rm.
6. Finally, it replaces the old HISTORY.md with the newly generated one.

A dry run can be performed to preview the changes:

DRY_RUN=1 unreleased_history/release.sh | less

Sources: source/lib/rocksdb/unreleased_history/README.txt:29-40, source/lib/rocksdb/unreleased_history/release.sh

Release Candidate (RC) Workflow

Releases are performed in two phases: one or more release candidates (RCs) followed by a final release. This ensures that a version is well-tested before being finalized. The process is modeled after the practices of core dependencies like librdkafka.

This sequence diagram illustrates the RC and final release process.

API and ABI Compatibility

Maintaining API and ABI compatibility is critical, especially for LTS releases, to ensure that existing applications do not break upon upgrading.

• Rule: Existing public APIs MUST NEVER be changed. This includes function signatures, return values, and public struct fields.
• Semantic Changes: Changes to a function's behavior are only allowed if the previous behavior was undocumented or clearly incorrect. All such changes must be highlighted in the "Upgrade considerations" section of the release notes.
• New APIs: New APIs should be designed to be future-proof. Public structs should be avoided in favor of private types with accessor methods to allow for future extension without breaking ABI.

Sources: source/lib/librdkafka-2.10.1/CONTRIBUTING.md:31-63

Summary

The release lifecycle for FluentDo Agent is a comprehensive process designed to deliver stable, reliable, and secure software. It combines a predictable, date-based release schedule with a robust 24-month LTS policy. The workflow integrates automated tooling for upstream synchronization and changelog management, alongside a disciplined release candidate process to ensure quality. By adhering to strict API/ABI compatibility rules, the project provides a dependable foundation for users in production environments.