feat(releasing): add deprecation.d fragment system

.github/CODEOWNERS

@@ -15,5 +15,6 @@ website/* @vectordotdev/vector @vectordotdev/vector-website
 # Keep documentation team paths in sync with .github/workflows/add_docs_review_label.yml
 /*.md @vectordotdev/vector @vectordotdev/documentation
 docs/ @vectordotdev/vector @vectordotdev/documentation
+deprecation.d/ @vectordotdev/vector @vectordotdev/documentation
 website/content @vectordotdev/vector @vectordotdev/documentation
 website/cue/reference @vectordotdev/vector @vectordotdev/documentation

.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 new deprecation announcements in this release.
 - [ ] PR review & approval.
 
 # On the day of release

.github/workflows/add_docs_review_label.yml

@@ -13,6 +13,7 @@ on:
     paths:
       - "*.md"
       - "docs/**"
+      - "deprecation.d/**"
       - "website/content/**"
       - "website/cue/reference/**"
 

.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,12 @@ jobs:
               - '**/Cargo.toml'
               - 'Cargo.lock'
               - ".github/workflows/deny.yml"
+            deprecations:
+              - 'deprecation.d/**'
+              - 'website/data/deprecations.json'
+              - "vdev/**"
+              - ".github/workflows/deprecation.yaml"
+              - ".github/workflows/changes.yml"
             cue:
               - 'website/cue/**'
               - "vdev/**"

.github/workflows/deprecation.yaml

@@ -0,0 +1,53 @@
+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 }}
+          fetch-tags: true
+
+      - uses: ./.github/actions/setup
+        with:
+          vdev: true
+          mold: false
+
+      - name: Check deprecation fragments
+        run: vdev deprecation check

CONTRIBUTING.md

@@ -313,7 +313,7 @@ git push
 
 ### Deprecations
 
-When deprecating functionality in Vector, see [DEPRECATION.md](docs/DEPRECATION.md).
+When deprecating functionality in Vector, see [DEPRECATION_POLICY.md](docs/DEPRECATION_POLICY.md).
 
 ### Dependencies
 
@@ -329,7 +329,7 @@ documents:
 
 1. **[DEVELOPING.md](docs/DEVELOPING.md)** - Everything necessary to develop
 2. **[DOCUMENTING.md](docs/DOCUMENTING.md)** - Preparing your change for Vector users
-3. **[DEPRECATION.md](docs/DEPRECATION.md)** - Deprecating functionality in Vector
+3. **[DEPRECATION_POLICY.md](docs/DEPRECATION_POLICY.md)** - Deprecating functionality in Vector
 
 ## Legal
 

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:
+
+- **`deprecation_announcements`** – items deprecated in this release (announced for the first time).
+- **`planned_deprecations`** – items deprecated in an earlier release.
+
+## File format
+
+Each file must be named `<unique_slug>.md` and begin with YAML frontmatter:
+
+````markdown
+---
+what: "`legacy_auth` configuration option"
+deprecated_since: "0.57.0"
+---
+
+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. |
+| `deprecated_since` | Yes | The release version in which this deprecation was first announced. Accepts a semver string (`0.56`, `0.56.0`). |
+
+### 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. **Removed** – when a deprecated feature is finally removed, the PR runs
+   `cargo vdev deprecation enact <slug> --version <removed-in-version>`. The command
+   records the removal in `website/data/deprecations.json` and deletes the fragment in
+   one step; deleting the fragment manually would drop it from `past_deprecations`.
+
+## Validation
+
+Run `cargo vdev deprecation check` 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,10 @@
+---
+what: "`azure_monitor_logs` sink"
+deprecated_since: "0.54.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,9 @@
+---
+what: "Boolean syntax for the `compression` field in the `vector` sink"
+deprecated_since: "0.56.0"
+---
+
+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,7 @@
+---
+what: "`buffer_byte_size` and `buffer_events` gauge metrics"
+deprecated_since: "0.53.0"
+---
+
+The `buffer_byte_size` and `buffer_events` gauges are deprecated in favor of the
+`buffer_size_bytes` and `buffer_size_events` metrics.

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

@@ -0,0 +1,9 @@
+---
+what: "`series_api_version: v1` option on the `datadog_metrics` sink"
+deprecated_since: "0.56.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/http-server-encoding.md

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