feat(releasing): add deprecation.d fragment system

.github/ISSUE_TEMPLATE/minor-release.md

@@ -65,7 +65,7 @@ Automated steps include:
   - [ ] Ensure any deprecations are highlighted in the release upgrade guide.
   - [ ] Review generated changelog entries to ensure they are understandable to end-users.
   - [ ] Ensure the date matches the scheduled release date.
-  - [ ] Add a link to pending deprecation items from [DEPRECATIONS.md](https://github.com/vectordotdev/vector/blob/master/docs/DEPRECATIONS.md).
+  - [ ] Run `cargo vdev deprecation show --version "${NEW_VECTOR_VERSION}"` to review enacted deprecations and verify the release notes reflect them correctly.
 - [ ] PR review & approval.
 
 # On the day of release

.github/workflows/changes.yml

@@ -34,6 +34,8 @@ on:
         value: ${{ jobs.source.outputs.dependencies }}
       deny:
         value: ${{ jobs.source.outputs.deny }}
+      deprecations:
+        value: ${{ jobs.source.outputs.deprecations }}
       internal_events:
         value: ${{ jobs.source.outputs.internal_events }}
       cue:
@@ -170,6 +172,7 @@ jobs:
       source: ${{ steps.filter.outputs.source }}
       dependencies: ${{ steps.filter.outputs.dependencies }}
       deny: ${{ steps.filter.outputs.deny }}
+      deprecations: ${{ steps.filter.outputs.deprecations }}
       internal_events: ${{ steps.filter.outputs.internal_events }}
       cue: ${{ steps.filter.outputs.cue }}
       component_docs: ${{ steps.filter.outputs.component_docs }}
@@ -223,6 +226,11 @@ jobs:
               - '**/Cargo.toml'
               - 'Cargo.lock'
               - ".github/workflows/deny.yml"
+            deprecations:
+              - 'deprecation.d/**'
+              - "vdev/**"
+              - ".github/workflows/deprecation.yaml"
+              - ".github/workflows/changes.yml"
             cue:
               - 'website/cue/**'
               - "vdev/**"

.github/workflows/deprecation.yaml

@@ -0,0 +1,52 @@
+name: Deprecation Fragments
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "Git ref to checkout"
+        required: false
+        type: string
+
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref to checkout"
+        required: false
+        type: string
+
+  pull_request:
+  merge_group:
+    types: [checks_requested]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number || github.sha }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  changes:
+    if: ${{ github.event_name == 'pull_request' }}
+    uses: ./.github/workflows/changes.yml
+    secrets: inherit
+
+  check-deprecations:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    if: ${{ always() && (github.event_name != 'pull_request' || needs.changes.outputs.deprecations == 'true') }}
+    needs: [changes]
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ inputs.ref }}
+
+      - uses: ./.github/actions/setup
+        with:
+          vdev: true
+          mold: false
+
+      - name: Check deprecation fragments
+        run: vdev check deprecations

deprecation.d/README.md

@@ -0,0 +1,63 @@
+# deprecation.d
+
+This directory contains deprecation notices for Vector.
+
+Each file describes a feature, configuration option, or behavior that is being deprecated.
+These notices are collected during the release process and rendered into two sections of the
+release notes:
+
+- **`deprecations`** – items whose removal version matches the current release (enacted now).
+- **`planned_deprecations`** – items scheduled for removal in a future release.
+
+## File format
+
+Each file must be named `<unique_slug>.md` and begin with YAML frontmatter:
+
+````markdown
+---
+announcement_version: next
+deprecation_version: 0.57.0
+what: "`legacy_auth` configuration option"
+---
+
+The `legacy_auth` option has been replaced by the new `auth` block.
+
+Migrate by replacing:
+
+```yaml
+legacy_auth: "my_token"
+```
+
+with:
+
+```yaml
+auth:
+  token: "my_token"
+```
+````
+
+### Frontmatter fields
+
+| Field | Required | Description |
+| ----- | -------- | ----------- |
+| `what` | Yes | Short one-line description of what is deprecated. |
+| `deprecation_version` | Yes | Version when the item will be removed. Accepts a semver string (`0.56`, `0.56.0`), `TBD` (unknown), or `next` (the very next release). |
+| `announcement_version` | Yes | Version when the deprecation was first announced. Accepts the same values as `deprecation_version`. Use `next` (recommended) when opening the PR — the release tooling will replace it with the concrete version automatically. |
+
+### Body
+
+The body of the file is an optional Markdown explanation: migration instructions, rationale,
+or links to further documentation. It is rendered verbatim in the release notes.
+
+## Lifecycle
+
+1. **Announce** – a PR adds a file to this directory when the deprecation is first introduced.
+2. **Planned** – every subsequent release lists the entry under `planned_deprecations`.
+3. **Enacted** – when the release version equals `deprecation_version`, the entry moves to
+   `deprecations` in the release notes and the file is removed from this directory.
+
+## Validation
+
+Run `cargo vdev check deprecations` to validate all files in this directory.
+
+To preview the current deprecation state, run `cargo vdev deprecation show`.

deprecation.d/azure-monitor-logs-sink.md

@@ -0,0 +1,11 @@
+---
+what: "`azure_monitor_logs` sink"
+announcement_version: 0.54.0
+deprecation_version: 0.58.0
+---
+
+The `azure_monitor_logs` sink is deprecated in favor of the new `azure_logs_ingestion` sink,
+which uses the Azure Monitor Logs Ingestion API.
+
+Users should migrate before Microsoft ends support for the old Data Collector API (scheduled
+for September 2026).

deprecation.d/bool-or-vector-compression.md

@@ -0,0 +1,10 @@
+---
+what: "Boolean syntax for the `compression` field in the `vector` sink"
+announcement_version: next
+deprecation_version: next
+---
+
+The boolean syntax (`compression: true` / `compression: false`) is deprecated.
+Use the string syntax instead: `compression: "gzip"`, `compression: "zstd"`, or `compression: "none"`.
+
+The `bool_or_vector_compression` deserializer will be removed once the boolean syntax is no longer supported.

deprecation.d/buffer-bytes-events-metrics.md

@@ -0,0 +1,8 @@
+---
+what: "`buffer_byte_size` and `buffer_events` gauge metrics"
+announcement_version: 0.53.0
+deprecation_version: TBD
+---
+
+The `buffer_byte_size` and `buffer_events` gauges are deprecated in favor of the
+`buffer_size_bytes` and `buffer_size_events` metrics described in `docs/specs/buffer.md`.

deprecation.d/datadog-metrics-series-v1.md

@@ -0,0 +1,10 @@
+---
+what: "`series_api_version: v1` option on the `datadog_metrics` sink"
+announcement_version: 0.55.0
+deprecation_version: 0.58.0
+---
+
+The `series_api_version: v1` option is deprecated in favor of `v2` (the default).
+The v1 series endpoint (`/api/v1/series`) is a legacy endpoint.
+
+Users should remove `series_api_version: v1` from their configuration or set it to `v2`.

deprecation.d/example-fake-deprecation.md

@@ -0,0 +1,7 @@
+---
+what: "FAKE EXAMPLE — `fake_option` on the `fake_sink` sink [remove before merging]"
+announcement_version: next
+deprecation_version: 0.58
+---
+
+This is a fake deprecation entry used to test the Deprecation Announcements section on the release page. Remove this file before merging.

deprecation.d/greptimedb-v0-support.md

@@ -0,0 +1,8 @@
+---
+what: "GreptimeDB v0.x support in `greptimedb_metrics` and `greptimedb_logs` sinks"
+announcement_version: 0.55.0
+deprecation_version: 0.56.0
+---
+
+The `greptimedb_metrics` and `greptimedb_logs` sinks drop support for GreptimeDB v0.x.
+Users must upgrade their GreptimeDB instance to v1.x before upgrading Vector.

deprecation.d/http-server-encoding.md

@@ -0,0 +1,7 @@
+---
+what: "`encoding` field on HTTP server sources"
+announcement_version: 0.50.0
+deprecation_version: TBD
+---
+
+The `encoding` field will be removed. Use `decoding` and `framing` instead.

docs/DEPRECATION.md

@@ -80,7 +80,13 @@ When introducing a deprecation into Vector, the pull request introducing the dep
   the new name will be appended with the text `(formerly OldName)`.
 - Add a log message to Vector that is logged at the `WARN` level starting with the word `DEPRECATION` if Vector detects
   the deprecated configuration or feature being used (when possible).
-- Add the deprecation to [docs/DEPRECATIONS.md](../docs/DEPRECATIONS.md) to track migration (if applicable) and removal
+- Add a deprecation notice file to [`deprecation.d/`](../deprecation.d/) following the format described in
+  [`deprecation.d/README.md`](../deprecation.d/README.md). Both `announcement_version` and `deprecation_version`
+  are required. Set `announcement_version` to `next` (recommended) or the current release version if known. Set
+  `deprecation_version` to the planned removal version, `TBD` if not yet decided, or `next` if removal is intended
+  for the very next release. The release tooling will replace any `next` values with the concrete version when the
+  release is cut. Run
+  `cargo vdev check deprecations` to validate the file.
 
 When removing a deprecation in a subsequent release, the pull request should:
 
@@ -90,4 +96,5 @@ When removing a deprecation in a subsequent release, the pull request should:
   for transitioning if applicable.
 - Copy the same note from the previous step, to a changelog fragment, with type="breaking". See the changelog
   fragment [README.md](../changelog.d/README.md) for details.
-- Remove the deprecation from [docs/DEPRECATIONS.md](../docs/DEPRECATIONS.md)
+- Remove the file from [`deprecation.d/`](../deprecation.d/) (the release tooling does this automatically when
+  `deprecation_version` matches the release being cut)

docs/DEPRECATIONS.md

@@ -1,27 +1,17 @@
-See [DEPRECATION.md](/docs/DEPRECATION.md#process) for the process for updating this file.
+Deprecation notices are now tracked in [`deprecation.d/`](../deprecation.d/) at the root of
+the repository.
 
-The format for each entry should be: `<version> <identifier> <description>`.
+Each file in that directory is a self-contained deprecation notice with YAML frontmatter.
+See [`deprecation.d/README.md`](../deprecation.d/README.md) for the file format and lifecycle.
 
-- `<version>` should be the version of Vector in which to take the action (deprecate, migrate, or
-  remove)
-- `<identifier>` should be a unique identifier that can also be used in the code to easily find the
-  places to modify
-- `<description>` should be a longer form description of the change to be made
+To view all current notices, run:
 
-For example:
+```shell
+cargo vdev deprecation show
+```
 
-- v0.34.0 legacy_openssl_provider OpenSSL legacy provider flag should be removed
+To validate the directory, run:
 
-## To be deprecated
-
-- `v0.50.0` | `http-server-encoding` | The `encoding` field will be removed. Use `decoding` and `framing` instead.
-- `v0.53.0` | `buffer-bytes-events-metrics` | The `buffer_byte_size` and `buffer_events` gauges are deprecated in favor of the `buffer_size_bytes`/`buffer_size_events` metrics described in `docs/specs/buffer.md`.
-- `v0.58.0` | `azure-monitor-logs-sink` | The `azure_monitor_logs` sink is deprecated in favor of the new `azure_logs_ingestion` sink, which uses the Azure Monitor Logs Ingestion API. Users should migrate before Microsoft ends support for the old Data Collector API (scheduled for September 2026).
-- `v0.57.0` | `bool-or-vector-compression` | The boolean syntax for the `compression` field in the `vector` sink (`compression: true`/`compression: false`) is deprecated. Use the string syntax instead (`compression: "gzip"`, `compression: "zstd"`, or `compression: "none"`). The `bool_or_vector_compression` deserializer should be removed once the boolean syntax is no longer supported.
-- `v0.58.0` | `datadog-metrics-series-v1` | The `series_api_version: v1` option on the `datadog_metrics` sink is deprecated in favor of `v2` (the default). The v1 series endpoint (`/api/v1/series`) is a legacy endpoint; users should remove `series_api_version: v1` from their configuration or set it to `v2`.
-
-## To be migrated
-
-## To be removed
-
-- `v0.56.0` | `greptimedb-v0-support` | The `greptimedb_metrics` and `greptimedb_logs` sinks drop support for GreptimeDB v0.x. Users must upgrade their GreptimeDB instance to v1.x before upgrading Vector.
+```shell
+cargo vdev check deprecations
+```

vdev/src/commands/check/deprecations.rs

@@ -0,0 +1,39 @@
+#![allow(clippy::print_stdout)]
+
+use anyhow::Result;
+
+use crate::utils::{deprecation, paths};
+
+/// Check that all deprecation.d fragments are valid
+#[derive(clap::Args, Debug)]
+#[command()]
+pub struct Cli {}
+
+impl Cli {
+    pub fn exec(self) -> Result<()> {
+        let repo_root = paths::find_repo_root()?;
+        let dir = repo_root.join(deprecation::DEPRECATION_DIR);
+
+        if !dir.is_dir() {
+            println!(
+                "No {dir} directory found; nothing to validate.",
+                dir = dir.display()
+            );
+            return Ok(());
+        }
+
+        let entries = deprecation::read_deprecation_fragments(&dir)?;
+
+        if entries.is_empty() {
+            println!("No deprecation fragments found in {}.", dir.display());
+            return Ok(());
+        }
+
+        for entry in &entries {
+            println!("  ok  {}", entry.filename);
+        }
+        println!("{} deprecation fragment(s) are valid.", entries.len());
+
+        Ok(())
+    }
+}

vdev/src/commands/check/mod.rs

@@ -1,5 +1,6 @@
 mod component_features;
 mod deny;
+mod deprecations;
 mod events;
 mod examples;
 mod fmt;
@@ -14,6 +15,7 @@ crate::cli_subcommands! {
     generated_docs,
     component_features,
     deny,
+    deprecations,
     docs,
     events,
     examples,

vdev/src/commands/deprecation/mod.rs

@@ -0,0 +1,6 @@
+mod show;
+
+crate::cli_subcommands! {
+    "Manage and inspect deprecation notices..."
+    show,
+}