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

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

Summary

Introduces a deprecation.d/ fragment system that tracks deprecations as structured markdown files with YAML frontmatter, replacing the hand-maintained docs/DEPRECATIONS.md table.

Each fragment carries:

what — short description of what's deprecated
deprecated_since — concrete semver (e.g. 0.56.0)
optional description — free-form Markdown migration guidance

New `vdev` commands

cargo vdev deprecation show [--version X.Y.Z] — list fragments grouped into announced / planned / enacted buckets for a target release
cargo vdev deprecation enact <slug> [--version X.Y.Z] — record an enacted entry in the generated JSON and remove the fragment
cargo vdev deprecation generate — regenerate website/cue/reference/generated/deprecations.json from fragments
cargo vdev check deprecations — validate fragments and ensure the generated JSON is up to date

CI

A new GitHub Actions workflow (.github/workflows/deprecation.yaml) runs vdev check deprecations when deprecation.d/ or the generated JSON change.

Website

CUE schema additions (#DeprecationEntry, #EnactedDeprecationEntry) and Hugo templates render deprecations on:

individual release pages — announced / planned / enacted partitions
/releases/deprecations index page
a {{< deprecations >}} shortcode for ad-hoc inclusion

The website build pipeline runs vdev deprecation generate before cue-build.

Migration

All 5 entries from docs/DEPRECATIONS.md migrated to fragment files
docs/DEPRECATIONS.md deleted
docs/DEPRECATION.md renamed to docs/DEPRECATION_POLICY.md (links updated in CONTRIBUTING.md, docs/REVIEWING.md)
Minor-release issue template updated to call the new vdev deprecation show / enact steps

Vector configuration

NA

How did you test this PR?

cargo test -p vdev — 59 tests pass
cargo clippy -p vdev — clean
cargo vdev check deprecations — validates all 5 migrated fragments and confirms generated JSON is up to date
cargo vdev deprecation show — verified bucket output
Hugo render: deprecation sections appear correctly on a local release page render

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

Related: fix(vdev): release tooling fixes from #25442 #25629 (release tooling fixes previously extracted from this branch)

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

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

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

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

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

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

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

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".

github-actions · 2026-06-17T17:32:23Z

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-06-17T17:33:03Z

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-06-17T17:33:15Z

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-06-17T17:33:17Z

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

Introduces a structured deprecation tracking system parallel to changelog.d: - `deprecation.d/` holds Markdown fragments with YAML frontmatter (`what`, `deprecated_since`, optional `description`), one per pending deprecation. README explains the policy and lifecycle. - `cargo vdev deprecation show [--version X.Y.Z]` lists fragments grouped into announced/planned/enacted buckets for a target release. - `cargo vdev deprecation enact <slug> [--version X.Y.Z]` records an enacted entry in the generated JSON and removes the fragment. - `cargo vdev deprecation generate` regenerates `website/cue/reference/generated/deprecations.json` from fragments. - `cargo vdev check deprecations` validates fragments and ensures the generated JSON is up to date. Wired into a GitHub Actions workflow triggered when `deprecation.d/` or the generated JSON change. - CUE schema (`#DeprecationEntry`, `#EnactedDeprecationEntry`) and Hugo templates (`releases/deprecations.html`, `partials/releases/deprecations.html`, `shortcodes/deprecations.html`) render deprecations on the release pages and on `/releases/deprecations`. - Existing deprecations from `docs/DEPRECATIONS.md` migrated to fragment files; the legacy doc is deleted. `docs/DEPRECATION.md` renamed to `docs/DEPRECATION_POLICY.md` for clarity (links updated). - Minor-release issue template updated to call out the new `vdev deprecation show`/`enact` steps. The website build pipeline runs `vdev deprecation generate` before `cue-build` so the generated JSON is always consumed alongside the cue sources.

Previously the per-release deprecations partial used HasPrefix on the major.minor pair, so a fragment with `deprecated_since: 0.56.1` would also render on the 0.56.0 release page (and similarly for enacted `removed_in`). Use exact equality against the page version, falling back to the shorthand `X.Y` form for fragments that omit the patch.

- "Removed" step now tells contributors to run `cargo vdev deprecation enact`, not to delete the fragment manually. Manual deletion drops the entry from `past_deprecations` instead of moving it there. - Validation command renamed: `cargo vdev check deprecations` → `cargo vdev deprecation check`.

The process and removal sections previously asked authors to copy the same migration text into the upgrade guide, the changelog fragment, and the deprecation.d/ fragment. With the fragment now rendered on the release page automatically, that duplication is wasted work. Reframe: - Deprecation.d fragment is the canonical, full migration guide. - Changelog fragment can be a short one-liner; it doesn't need to repeat the migration body. - Removed the "add a note to the upgrade guide highlights" requirement; highlights remain optional for richer treatment, not duplicate text. - Validation command renamed: `cargo vdev check deprecations` → `cargo vdev deprecation check`.

github-actions · 2026-06-17T19:21: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-06-17T19:21:26Z

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-06-17T19:21:31Z

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

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4733eb45bc

ℹ️ About Codex in GitHub

Your team has set up Codex to 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 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

The deprecations index lived at /releases/deprecations/ because the content file was under content/en/releases/. That coupled the URL to the releases section even though the page is its own concept (an always-current catalog of active and past deprecations, not a release artifact). Move: content/en/releases/deprecations.md -> content/en/deprecations.md layouts/releases/deprecations.html -> layouts/_default/deprecations.html New URL: /deprecations/. Updated the intra-link in the per-release deprecations partial to point at the new path.

github-actions · 2026-06-17T19:34:23Z

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-06-17T19:34:32Z

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-06-17T19:34:33Z

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

…t flow The "Deprecation" and "Removal" sections still promised that we notify users via the release upgrade guide, but the rewritten Process section treats the deprecation.d fragment (rendered on the release page and the deprecations index) as the canonical user-facing notification. Update both lifecycle sections to match: the fragment / enacted entry is the default; the upgrade guide remains an option for richer treatment when warranted, not a per-deprecation requirement.

github-actions · 2026-06-17T19:37:28Z

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-06-17T19:37:33Z

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-06-17T19:37:38Z

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

thomasqueirozb · 2026-06-17T19:41:44Z

+generate-deprecations-json:
+	$(VDEV) deprecation generate
+
+structured-data: generate-vrl-docs generate-deprecations-json cue-build config-examples


Reminder to update the vdev version in website amplify configuration

thomasqueirozb · 2026-06-17T19:47:51Z

+- Add a changelog fragment with `type="deprecation"` ([`changelog.d/README.md`](../changelog.d/README.md)). A short
+  one-line summary is sufficient — the deprecation fragment is the canonical migration guide and is rendered on the
+  release page automatically.
+- Add a deprecation note to the component docs. Typically, this means adding `deprecation: "description of the deprecation"`


Suggested change

- Add a deprecation note to the component docs. Typically, this means adding `deprecation: "description of the deprecation"`

- Add a deprecation note to the component docs if applicable. Typically, this means adding `deprecation: "description of the deprecation"`

to the cue file or `#[configurable(deprecated = "use <alternative> instead")]` to the parameter.

thomasqueirozb · 2026-06-17T19:49:09Z

+- Add a changelog fragment with `type="breaking"` ([`changelog.d/README.md`](../changelog.d/README.md)). A short
+  one-line summary is sufficient — the enacted deprecation entry is the canonical record of what was removed.


Should we even include a changelog? This will be its own section in the release. I think we can fully remove this entry from this doc

thomasqueirozb · 2026-06-17T19:50:27Z

+	#DeprecationEntry: {
+		what:             string
+		deprecated_since: string
+		description?:     string
+	}
+
+	#EnactedDeprecationEntry: {
+		what:             string
+		deprecated_since: string
+		removed_in:       string
+		description?:     string
+	}


Suggested change

#DeprecationEntry: {

what: string

deprecated_since: string

description?: string

}

#EnactedDeprecationEntry: {

what: string

deprecated_since: string

removed_in: string

description?: string

}

#DeprecationEntry: {

what: string

deprecated_since: string

description: string

}

#EnactedDeprecationEntry: #DeprecationEntry | {

removed_in: string

}

We should likely require description and I think this works/makes it shorter

thomasqueirozb · 2026-06-17T19:52:49Z

+  - [ ] Run `cargo vdev deprecation show --version "${NEW_VECTOR_VERSION}"` to review new deprecation announcements in this release.
+  - [ ] Run `cargo vdev deprecation enact <slug> --version "${NEW_VECTOR_VERSION}"` for any deprecations being removed in this release, then commit all resulting changes (deleted fragment and updated `website/data/deprecations.json`).


Maybe we delete this from the release template? This would have been done in a previous PR and should likely not be part of the release. If it is then we did something wrong beforehand

Suggested change

- [ ] Run `cargo vdev deprecation show --version "${NEW_VECTOR_VERSION}"` to review new deprecation announcements in this release.

- [ ] Run `cargo vdev deprecation enact <slug> --version "${NEW_VECTOR_VERSION}"` for any deprecations being removed in this release, then commit all resulting changes (deleted fragment and updated `website/data/deprecations.json`).

…line per review

github-actions · 2026-06-17T21:16:30Z

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-06-17T21:16:35Z

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-06-17T21:16:37Z

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

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

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

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

Comment thread deprecation.d/bool-or-vector-compression.md Outdated

Comment thread deprecation.d/example-fake-deprecation.md Outdated

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/DEPRECATION.md Outdated

pront mentioned this pull request Jun 17, 2026

chore(vdev): bump version to 0.3.4 #25645

Merged

9 tasks

pront added 4 commits June 17, 2026 15:15

pront force-pushed the website-deprecation-d-releasing branch from 8fadf02 to 4733eb4 Compare June 17, 2026 19:20

pront approved these changes Jun 17, 2026

View reviewed changes

github-actions Bot removed the docs review on hold The documentation team reviews PRs only after a PR is approved by the COSE team. label Jun 17, 2026

chatgpt-codex-connector Bot reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/DEPRECATION_POLICY.md

github-actions Bot added the docs review on hold The documentation team reviews PRs only after a PR is approved by the COSE team. label Jun 17, 2026

thomasqueirozb commented Jun 17, 2026

View reviewed changes

docs(deprecation policy): tighten the deprecation changelog fragment …

b83712f

…line per review

	- Add a deprecation note to the component docs. Typically, this means adding `deprecation: "description of the deprecation"`
	- Add a deprecation note to the component docs if applicable. Typically, this means adding `deprecation: "description of the deprecation"`
	to the cue file or `#[configurable(deprecated = "use <alternative> instead")]` to the parameter.

		- Add a changelog fragment with `type="breaking"` ([`changelog.d/README.md`](../changelog.d/README.md)). A short
		one-line summary is sufficient — the enacted deprecation entry is the canonical record of what was removed.

		- [ ] Run `cargo vdev deprecation show --version "${NEW_VECTOR_VERSION}"` to review new deprecation announcements in this release.
		- [ ] Run `cargo vdev deprecation enact <slug> --version "${NEW_VECTOR_VERSION}"` for any deprecations being removed in this release, then commit all resulting changes (deleted fragment and updated `website/data/deprecations.json`).

Conversation

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

Uh oh!

Summary

New vdev commands

CI

Website

Migration

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!

Uh oh!

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

thomasqueirozb commented May 15, 2026 •

edited by pront

Loading

New `vdev` commands