Project: Vector (Observability and Analysis / Observability)
File: VERSIONING.md

This document covers Vector's versioning and what it means as a user of Vector. Please note, Vector is currently in its pre-1.0 phase and quickly approaching 1.0. Minor version increments can introduce breaking changes during this phase. Please see the section for more info. <!-- MarkdownTOC autolink="true" style="ordered" indent=" " --> 1. 1. 1. 1. <!-- /MarkdownTOC --> Vector adheres to the [Semantic Versioning 2.0] convention. In summary: Versions follow the `MAJOR.MINOR.PATCH` format (i.e., `2.5.1`) `PATCH` increments only when backward compatible bug fixes are introduced. `MINOR` increments only when new, backward compatible functionality is introduced. `MAJOR` increments if any backwards incompatible changes are introduced. Pre `1.0` (major version `0`) is for initial development and `MINOR` version bumps can introduce breaking changes. Semantic Versioning hinges on Vector's definition of "public API". By the nature of Vector -- a tool that collects, processes, and routes data from disparate systems -- it has a very large public surface area. It's not immediately obvious which parts are covered under our versioning contract and how they're covered. This section aims to remove all ambiguity in this area. The following Vector areas are covered in Vector's definition of public API. The follow Vector areas are intended for public consumption (consumption by anything other than Vector itself). Backward incompatible changes will trigger a major version increment. [CLI] Flags Exit codes [Data model] As output in all sinks except the [`vector` sink] As exposed in the source of the [`lua` transform] [GraphQL API] Telemetry Vector's internal metrics as provided by the [`internal_metrics` source] [VRL] The following Vector areas are intended for private consumption (consumption by Vector only). Backward incompatible changes will trigger a major version increment only if Vector itself is not compatible with previous versions. [Configuration schema] [Data directory] and its contents [Data model] As output in the [`vector` sink] The following Vector areas are not covered in Vector's definition of Public API. Breaking changes in these areas will not trigger a major version increment. [CLI] The standard output (`STDOUT` and `STDERR`). [Installation workflows] Telemetry Vector's internal logs as provided through `STDOUT`, `STDERR`, and the [`internal_logs` source] Please see the [release policy]. As defined by [Semantic Versioning], you can expect no breaking changes. Users will be able to seamlessly upgrade without any action. Major versions break backward compatibility. Vector takes breaking changes very seriously. We understand that Vector is a critical part of your infrastructure and breaking changes introduce downtime. We will make every effort necessary to avoid them. If we introduce them we will make the upgrade process as painless as possible. Every major release will come with a single, step-by-step upgrade guide in the [release notes]. As defined by [Semantic Versioning]: major version zero (0.y.z) is for initial development. Anything MAY change at any time. And while this is true to the spec, Vector takes breaking changes very seriously during this phase. What's outlined in the section still holds true here. Each minor release bump will include an upgrade guide in the [release notes] if necessary.