Skip to content

Commit 83848ea

Browse files
prontpront
committed
feat(releasing): add deprecation.d fragment system
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.
1 parent d0d55b0 commit 83848ea

23 files changed

Lines changed: 473 additions & 35 deletions

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,6 @@ website/* @vectordotdev/vector @vectordotdev/vector-website
1313
# Keep documentation team paths in sync with .github/workflows/add_docs_review_label.yml
1414
/*.md @vectordotdev/vector @vectordotdev/documentation
1515
docs/ @vectordotdev/vector @vectordotdev/documentation
16+
deprecation.d/ @vectordotdev/vector @vectordotdev/documentation
1617
website/content @vectordotdev/vector @vectordotdev/documentation
1718
website/cue/reference @vectordotdev/vector @vectordotdev/documentation

‎.github/ISSUE_TEMPLATE/minor-release.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ Automated steps include:
6565
- [ ] Ensure any deprecations are highlighted in the release upgrade guide.
6666
- [ ] Review generated changelog entries to ensure they are understandable to end-users.
6767
- [ ] Ensure the date matches the scheduled release date.
68-
- [ ] Add a link to pending deprecation items from [DEPRECATIONS.md](https://github.com/vectordotdev/vector/blob/master/docs/DEPRECATIONS.md).
68+
- [ ] Run `cargo vdev deprecation show --version "${NEW_VECTOR_VERSION}"` to review new deprecation announcements in this release.
69+
- [ ] 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`).
6970
- [ ] PR review & approval.
7071

7172
# On the day of release

‎.github/workflows/add_docs_review_label.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ on:
1313
paths:
1414
- "*.md"
1515
- "docs/**"
16+
- "deprecation.d/**"
1617
- "website/content/**"
1718
- "website/cue/reference/**"
1819

‎.github/workflows/changes.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ on:
3434
value: ${{ jobs.source.outputs.dependencies }}
3535
deny:
3636
value: ${{ jobs.source.outputs.deny }}
37+
deprecations:
38+
value: ${{ jobs.source.outputs.deprecations }}
3739
internal_events:
3840
value: ${{ jobs.source.outputs.internal_events }}
3941
cue:
@@ -170,6 +172,7 @@ jobs:
170172
source: ${{ steps.filter.outputs.source }}
171173
dependencies: ${{ steps.filter.outputs.dependencies }}
172174
deny: ${{ steps.filter.outputs.deny }}
175+
deprecations: ${{ steps.filter.outputs.deprecations }}
173176
internal_events: ${{ steps.filter.outputs.internal_events }}
174177
cue: ${{ steps.filter.outputs.cue }}
175178
component_docs: ${{ steps.filter.outputs.component_docs }}
@@ -223,6 +226,12 @@ jobs:
223226
- '**/Cargo.toml'
224227
- 'Cargo.lock'
225228
- ".github/workflows/deny.yml"
229+
deprecations:
230+
- 'deprecation.d/**'
231+
- 'website/data/deprecations.json'
232+
- "vdev/**"
233+
- ".github/workflows/deprecation.yaml"
234+
- ".github/workflows/changes.yml"
226235
cue:
227236
- 'website/cue/**'
228237
- "vdev/**"

‎.github/workflows/deprecation.yaml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Deprecation Fragments
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
ref:
7+
description: "Git ref to checkout"
8+
required: false
9+
type: string
10+
11+
workflow_dispatch:
12+
inputs:
13+
ref:
14+
description: "Git ref to checkout"
15+
required: false
16+
type: string
17+
18+
pull_request:
19+
merge_group:
20+
types: [checks_requested]
21+
22+
concurrency:
23+
group: ${{ github.workflow }}-${{ github.event.number || github.sha }}
24+
cancel-in-progress: true
25+
26+
permissions:
27+
contents: read
28+
29+
jobs:
30+
changes:
31+
if: ${{ github.event_name == 'pull_request' }}
32+
uses: ./.github/workflows/changes.yml
33+
secrets: inherit
34+
35+
check-deprecations:
36+
runs-on: ubuntu-24.04
37+
timeout-minutes: 10
38+
if: ${{ always() && (github.event_name != 'pull_request' || needs.changes.outputs.deprecations == 'true') }}
39+
needs: [changes]
40+
steps:
41+
- name: Checkout branch
42+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
43+
with:
44+
ref: ${{ inputs.ref }}
45+
fetch-tags: true
46+
47+
- uses: ./.github/actions/setup
48+
with:
49+
vdev: true
50+
mold: false
51+
52+
- name: Check deprecation fragments
53+
run: vdev deprecation check

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ git push
313313

314314
### Deprecations
315315

316-
When deprecating functionality in Vector, see [DEPRECATION.md](docs/DEPRECATION.md).
316+
When deprecating functionality in Vector, see [DEPRECATION_POLICY.md](docs/DEPRECATION_POLICY.md).
317317

318318
### Dependencies
319319

@@ -329,7 +329,7 @@ documents:
329329

330330
1. **[DEVELOPING.md](docs/DEVELOPING.md)** - Everything necessary to develop
331331
2. **[DOCUMENTING.md](docs/DOCUMENTING.md)** - Preparing your change for Vector users
332-
3. **[DEPRECATION.md](docs/DEPRECATION.md)** - Deprecating functionality in Vector
332+
3. **[DEPRECATION_POLICY.md](docs/DEPRECATION_POLICY.md)** - Deprecating functionality in Vector
333333

334334
## Legal
335335

‎deprecation.d/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# deprecation.d
2+
3+
This directory contains deprecation notices for Vector.
4+
5+
Each file describes a feature, configuration option, or behavior that is being deprecated.
6+
These notices are collected during the release process and rendered into two sections of the
7+
release notes:
8+
9+
- **`deprecation_announcements`** – items deprecated in this release (announced for the first time).
10+
- **`planned_deprecations`** – items deprecated in an earlier release.
11+
12+
## File format
13+
14+
Each file must be named `<unique_slug>.md` and begin with YAML frontmatter:
15+
16+
````markdown
17+
---
18+
what: "`legacy_auth` configuration option"
19+
deprecated_since: "0.57.0"
20+
---
21+
22+
The `legacy_auth` option has been replaced by the new `auth` block.
23+
24+
Migrate by replacing:
25+
26+
```yaml
27+
legacy_auth: "my_token"
28+
```
29+
30+
with:
31+
32+
```yaml
33+
auth:
34+
token: "my_token"
35+
```
36+
````
37+
38+
### Frontmatter fields
39+
40+
| Field | Required | Description |
41+
| ----- | -------- | ----------- |
42+
| `what` | Yes | Short one-line description of what is deprecated. |
43+
| `deprecated_since` | Yes | The release version in which this deprecation was first announced. Accepts a semver string (`0.56`, `0.56.0`). |
44+
45+
### Body
46+
47+
The body of the file is an optional Markdown explanation: migration instructions, rationale,
48+
or links to further documentation. It is rendered verbatim in the release notes.
49+
50+
## Lifecycle
51+
52+
1. **Announce** – a PR adds a file to this directory when the deprecation is first introduced.
53+
2. **Planned** – every subsequent release lists the entry under `planned_deprecations`.
54+
3. **Removed** – when a deprecated feature is finally removed, the PR deletes the file from this directory.
55+
56+
## Validation
57+
58+
Run `cargo vdev check deprecations` to validate all files in this directory.
59+
60+
To preview the current deprecation state, run `cargo vdev deprecation show`.

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
what: "`azure_monitor_logs` sink"
3+
deprecated_since: "0.54.0"
4+
---
5+
6+
The `azure_monitor_logs` sink is deprecated in favor of the new `azure_logs_ingestion` sink,
7+
which uses the Azure Monitor Logs Ingestion API.
8+
9+
Users should migrate before Microsoft ends support for the old Data Collector API (scheduled
10+
for September 2026).

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
what: "Boolean syntax for the `compression` field in the `vector` sink"
3+
deprecated_since: "0.56.0"
4+
---
5+
6+
The boolean syntax (`compression: true` / `compression: false`) is deprecated.
7+
Use the string syntax instead: `compression: "gzip"`, `compression: "zstd"`, or `compression: "none"`.
8+
9+
The `bool_or_vector_compression` deserializer will be removed once the boolean syntax is no longer supported.

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
what: "`buffer_byte_size` and `buffer_events` gauge metrics"
3+
deprecated_since: "0.53.0"
4+
---
5+
6+
The `buffer_byte_size` and `buffer_events` gauges are deprecated in favor of the
7+
`buffer_size_bytes` and `buffer_size_events` metrics.

0 commit comments

Comments
 (0)