feat(releasing): add deprecation.d fragment system by thomasqueirozb · Pull Request #25442 · vectordotdev/vector

thomasqueirozb · 2026-05-15T13:37:21Z

Summary

Introduces a structured deprecation.d/ directory to track deprecation notices as versioned markdown fragments, replacing the hand-maintained docs/DEPRECATIONS.md table.

Each fragment has YAML frontmatter with what, deprecation_version (semver or TBD; accepts major.minor shorthand), and a required announcement_version. Both fields accept next as a value (the very next release) — the release tooling rewrites next to the concrete version automatically. The body is free-form Markdown for migration guidance.

Two new vdev commands:

cargo vdev check deprecations — validates all fragments (wired into CI via .github/workflows/deprecation.yaml)
cargo vdev deprecation show [--version X.Y.Z] — displays notices grouped by enacted in next release, announced in next release, and pre-existing

The release CUE generator now reads deprecation.d/ and renders three new sections: deprecations (enacted), deprecation_announcements (newly announced), and planned_deprecations (pre-existing). Enacted and announced fragment files are rewritten/retired automatically, mirroring changelog fragment handling.

All 6 existing entries from docs/DEPRECATIONS.md have been migrated to fragments. docs/DEPRECATION.md and the minor release issue template are updated accordingly.

Notes for reviewers

The following commits are intentionally reverted from this PR and should be restored after review:

986bc32 — feat(releasing): expose generate-cue as standalone release subcommand
55fc56d — feat(releasing): in dry-run mode, create branches from current branch instead of master
a0d2606 — fake deprecation entry and generated 0.56.0 CUE used for local website testing

Vector configuration

NA

How did you test this PR?

cargo test -p vdev — 66 tests pass
cargo vdev check deprecations — validates all 6 migrated fragments
cargo vdev deprecation show — verified grouped output with color
cargo vdev release prepare --version 0.56.0 --vrl-version 0.32.0 --dry-run
- Generated the full 0.56.0 CUE
- Deprecation sections render correctly at http://localhost:1313/releases/0.56.0/
- Verified that example-fake-deprecation.md updates next to 0.56.0

Change Type

Is this a breaking change?

Yes
No

Does this PR include user facing changes?

Yes. Please add a changelog fragment based on our guidelines.
No. A maintainer will apply the no-changelog label to this PR.

References

NA

…ow commands and release integration

github-actions · 2026-05-15T13:37:50Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T14:03:08Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

…h script" This reverts commit 6d0e0c0.

…check

github-actions · 2026-05-15T14:16:21Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

…lease CUE schema

github-actions · 2026-05-15T14:27:36Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

…rsion not announcement_version

github-actions · 2026-05-15T14:30:18Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

…gments

github-actions · 2026-05-15T14:36:37Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

… keyword, rewrite next on release

github-actions · 2026-05-15T15:11:58Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

…r new fragment fields

…s and datadog_metrics series v1

… and next-release detection

…keyword

github-actions · 2026-05-15T17:31:17Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T17:31:23Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-05-15T17:31:31Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

github-actions · 2026-05-15T17:37:25Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T17:37:30Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-05-15T17:37:31Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

…log array not the first ]

…tion.d README

…authenticated GitHub API

…ad of unauthenticated GitHub API" This reverts commit 3b2a6f0.

github-actions · 2026-05-15T18:05:42Z

Your preview site for the vector.dev will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
vector.dev preview

github-actions · 2026-05-15T18:05:47Z

Your preview site for the Rust Doc will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
Rust Doc preview

github-actions · 2026-05-15T18:05:48Z

Your preview site for the VRL Playground will be ready in a few minutes, please allow time for it to build.

Heres your preview link:
VRL Playground preview

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0bc71ccdd4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-05-15T18:15:31Z

@@ -0,0 +1,7 @@
+---
+what: "FAKE EXAMPLE — `fake_option` on the `fake_sink` sink [remove before merging]"


Remove the fake deprecation fragment before merge

This file is parsed as a real deprecation entry (the loader includes all .md files except README.md), so it is emitted into release metadata and user-facing notes; the generated 0.56.0.cue in this same commit already includes this fake item under deprecation_announcements. Leaving it in deprecation.d will pollute future release outputs with test-only content.

Useful? React with 👍 / 👎.

pront · 2026-05-19T13:28:06Z

  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`


Do we need announcement_version? We can incorporate to the release process like we do for the changelog.d fragments.

Also, let's remove the TBD and next from the accepted values for deprecation_version. We should always set a version number.

One more concern, setting the deprecation_version is a new commitment now, we could keep it like this for now but I wouldn't want to delay a release for this. I think the simplest way to workaround this is to bump deprecation_version before a release.

Do we need announcement_version? We can incorporate to the release process like we do for the changelog.d fragments.

Useful since I added a planned_deprecations section to the release, which gets rendered at the bottom. It is fully incorporated into the release process.

Also, let's remove the TBD and next from the accepted values for deprecation_version. We should always set a version number.

OK with removing TBD, but keeping next is a good idea so that PRs don't need to hard code deprecation versions. Hypothetical scenario: PR opened after 0.55 release set the deprecation_version to 0.56 but the PR only got merged after the 0.56 release. The deprecation version would then be in the past

One more concern, setting the deprecation_version is a new commitment now, we could keep it like this for now but I wouldn't want to delay a release for this. I think the simplest way to workaround this is to bump deprecation_version before a release.

Agreed. I added the deprecation vdev command helper to help us keep track of this a little better. Worst case scenario we just bump the version before the release.

Useful since I added a planned_deprecations section to the release, which gets rendered at the bottom. It is fully incorporated into the release process.

My goal is to simplify this process as much as possible. I believe we can drop this version completely and bundle this in the deprecation policy. We can state that once the deprecation fragment is merged, it will be announced with the next release.

The deprecation version would then be in the past

I believe that's fine since we don't promise to actually delete the deprecated functionality. The intention is to communicate that we will not remove functionality before a version X.

pront · 2026-05-19T13:34:17Z

+                for line in e.description.lines() {
+                    writeln!(s, "\t\t\t\t{line}").unwrap();
+                }
+                s.push_str("\t\t\t\t\"\"\"#\n");


Nit: Is there any cue related crate to help with this?

pront · 2026-05-19T13:35:08Z

+
+	whats_next: []
+
+	deprecations: [


Reminder to delete release artifacts.

feat(releasing): add deprecation.d fragment system with vdev check/sh…

f5643b6

…ow commands and release integration

thomasqueirozb added the no-changelog Changes in this PR do not need user-facing explanations in the release changelog label May 15, 2026

github-actions Bot added domain: ci Anything related to Vector's CI environment domain: vdev Anything related to the vdev tooling docs review on hold The documentation team reviews PRs only after a PR is approved by the COSE team. labels May 15, 2026

chore(ci): wire deprecation check into changelog.yaml via bash script

6d0e0c0

thomasqueirozb added 2 commits May 15, 2026 10:14

Revert "chore(ci): wire deprecation check into changelog.yaml via bas…

411a957

…h script" This reverts commit 6d0e0c0.

chore(ci): use changes.yml and setup action for deprecation fragment …

f2b55c2

…check

thomasqueirozb added 2 commits May 15, 2026 10:16

chore(ci): remove stale comment from deprecation workflow

a42c0a4

chore(internal docs): add deprecations and planned_deprecations to re…

9e5a2eb

…lease CUE schema

github-actions Bot added the domain: external docs Anything related to Vector's external, public documentation label May 15, 2026

chore(internal docs): fix deprecation fragments to use deprecation_ve…

1196d69

…rsion not announcement_version

chore(internal docs): restore announcement_version to deprecation fra…

d7b55a2

…gments

feat(releasing): make announcement_version required, add next version…

a0b1f0f

… keyword, rewrite next on release

thomasqueirozb added 9 commits May 15, 2026 11:15

chore(internal docs): update deprecation docs and release template fo…

37eba35

…r new fragment fields

feat(releasing): sort deprecation show output by version

9659a52

chore(internal docs): fix announcement versions for azure_monitor_log…

5ae8acd

…s and datadog_metrics series v1

feat(releasing): refine deprecation show output with grouped sections…

0b535c6

… and next-release detection

feat(releasing): add color and styling to deprecation show output

d1eff3a

fix(releasing): fix label alignment in deprecation show output

a2928a7

feat(releasing): colour concrete next-minor version red same as next …

b575eb9

…keyword

chore(internal docs): correct deprecation versions in fragments

0c6d247

feat(releasing): expose generate-cue as standalone release subcommand

986bc32

chore(internal docs): remove leading 'The' from deprecation what fields

9bc543d

thomasqueirozb added 8 commits May 15, 2026 13:57

chore(external docs): Add fake deprecation + generated cue file

a0d2606

chore(internal docs): fix nested code fences in deprecation.d README

12c78d3

chore(website): delete generated files

fd52722

fix(releasing): fix insert_block_after_changelog to target the change…

8eb5b42

…log array not the first ]

chore(internal docs): fix markdown table separator spacing in depreca…

9dabc01

…tion.d README

chore(releasing): use gh CLI to fetch VRL release notes instead of un…

3b2a6f0

…authenticated GitHub API

chore(website): add generated files

62479c0

Revert "chore(releasing): use gh CLI to fetch VRL release notes inste…

0bc71cc

…ad of unauthenticated GitHub API" This reverts commit 3b2a6f0.

thomasqueirozb force-pushed the website-deprecation-d-releasing branch from d2b0864 to 0bc71cc Compare May 15, 2026 18:05

thomasqueirozb marked this pull request as ready for review May 15, 2026 18:10

thomasqueirozb requested review from a team as code owners May 15, 2026 18:10

thomasqueirozb changed the title ~~feat(releasing): add deprecation.d fragment system with vdev check/show commands and release integration~~ feat(releasing): add deprecation.d fragment system May 15, 2026

chatgpt-codex-connector Bot reviewed May 15, 2026

View reviewed changes

thomasqueirozb mentioned this pull request May 15, 2026

chore(releasing): use gh CLI to fetch VRL release notes instead of unauthenticated GitHub API #25444

Merged

9 tasks

pront reviewed May 19, 2026

View reviewed changes

Comment thread docs/DEPRECATIONS.md

pront reviewed May 19, 2026

View reviewed changes

		@@ -0,0 +1,7 @@
		---
		what: "FAKE EXAMPLE — `fake_option` on the `fake_sink` sink [remove before merging]"

Conversation

thomasqueirozb commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes for reviewers

Vector configuration

How did you test this PR?

Change Type

Is this a breaking change?

Does this PR include user facing changes?

References

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

pront May 19, 2026

Choose a reason for hiding this comment

Uh oh!

thomasqueirozb May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pront May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pront May 19, 2026

Choose a reason for hiding this comment

Uh oh!

pront May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thomasqueirozb commented May 15, 2026 •

edited

Loading

thomasqueirozb May 19, 2026 •

edited

Loading