VERSIONING.md

Versioning

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 FAQ section for more info.

1. Convention
2. Public API
   1. Areas that are covered
      1. Intended for public consumption
      2. Intended for private consumption
   2. Areas that are NOT covered
3. FAQ
   1. How often is Vector released?
   2. How does Vector treat patch and minor versions?
   3. How does Vector treat major versions (breaking changes)?
   4. How does Vector treat pre-1.0 versions?

Convention

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.

Public API

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.

Areas that are covered

The following Vector areas are covered in Vector's definition of public API.

Intended for public consumption

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

Intended for private consumption

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

Areas that are NOT covered

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]

FAQ

How often is Vector released?

Please see the release policy.

How does Vector treat patch and minor versions?

As defined by Semantic Versioning, you can expect no breaking changes. Users will be able to seamlessly upgrade without any action.

How does Vector treat major versions (breaking changes)?

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.

How does Vector treat pre-1.0 versions?

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 major versions section still holds true here. Each minor release bump will include an upgrade guide in the release notes if necessary.