feat: Add changelog tracking to attribute definitions by ericapisani · Pull Request #270 · getsentry/sentry-conventions

ericapisani · 2026-02-27T19:53:31Z

Fixes #268 and CON-82

Add a changelog field to attribute definitions that tracks how each attribute has changed across sentry-conventions release versions.

This makes it possible to show users when an attribute was introduced, deprecated, or changed — which is useful context when browsing the attribute docs or consuming the metadata in SDKs.

What's included

Schema (schemas/attribute.schema.json): New optional changelog array with version, prs, and description fields
Generation script (scripts/generate_attribute_changelog.ts): Derives changelog entries from git tags and commit history, extracting PR numbers from commit messages
Code generators (scripts/generate_attributes.ts): Propagates changelog into the generated TypeScript (ChangelogEntry interface on AttributeMetadata) and Python (ChangelogEntry dataclass) outputs
Docs UI (docs/src/components/AttributeCard.astro): Renders a collapsible "Changelog" section on each attribute card, linking to PRs on GitHub
Tests (test/attributes.test.ts): Validates changelog entry structure and ordering (newest first)
All attribute JSON files: Populated with generated changelog entries based on git history

Screenshots

Add a changelog field to attribute JSON files that tracks how each attribute has changed across sentry-conventions release versions. This includes the schema extension, a generation script that derives changelog entries from git tags and commit history, updates to both TypeScript and Python code generators, docs UI rendering, and validation tests. Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-02-27T19:53:47Z

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

New Features ✨

(http) Add http.server.request.time_in_queue attribute by dingsdax in #267
(resource) Add resource.deployment.environment by mjq in #266

Add changelog tracking to attribute definitions by ericapisani in #270

Bug Fixes 🐛

(gen_ai) Input and output token description by obostjancic in #261

Documentation 📚

Update README with up-to-date links by ericapisani in #258

Internal Changes 🔧

Deps

Bump svelte from 5.51.5 to 5.53.5 by dependabot in #271
Bump rollup from 4.40.1 to 4.59.0 by dependabot in #269
Bump svelte from 5.48.1 to 5.51.5 by dependabot in #260

Other

(ai) Deprecate rest of ai.* attributes by constantinius in #264
(deps-dev) Bump tar from 7.5.7 to 7.5.8 by dependabot in #259
(gen_ai) Deprecate gen_ai.tool.input, gen_ai.tool.message, gen_ai.tool.output by constantinius in #265

_{🤖 This preview updates automatically when you update the PR.}

Run biome formatter across all JSON model files to inline short arrays, and replace non-null assertions with optional chaining or type casts to satisfy biome's noNonNullAssertion rule. Co-Authored-By: Claude <noreply@anthropic.com>

Lms24

Nice! I really like the idea of the changelog. I missed this in the past when working on PRs like #208, so having this transparency feels like a win!

I had a question regarding manual changelog entries and how/when to run the changelog generation script.

Lms24 · 2026-03-02T13:57:35Z

scripts/generate_attribute_changelog.ts

+    }
+
+    const attributeJson = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as AttributeJson;
+    attributeJson.changelog = changelog;


m: does this overwrite pre-existing changelog entries? I'm not sure if I'm missing something but it seems like in the future, we might want to run this script again for PRs that touch a lot of files (like #127) but there's also value in manually writing a changelog entry (for example, if we change semantics of an attribute like in #208 and add a description to the changelog). Would we overwrite the manually added entry when rerunning the script?

Lms24 · 2026-03-02T14:05:37Z

package.json

@@ -29,6 +29,7 @@
    "create:attribute": "tsx scripts/create_attribute.ts",

    "generate": "tsx scripts/generate.ts && yarn format",
+    "generate:attribute-changelog": "tsx scripts/generate_attribute_changelog.ts",


m: I assume we want to run this on every new PR, correct? Can we adjust the generate script to also execute the changelog generation script? This way contributors only need to remember running the already existing yarn generate command.

l: I'm not sure how well this works in conjunction with manual entries but: Should we fail CI if running this script produces changes? I think we should get this for free when we add this script to the generate command as suggested above. WDYT?

Lms24 · 2026-03-02T14:10:48Z

Actually, one more Q: What about unreleased changes? If I make a change to an attribute today, it's unlikely I don't yet know which version will be the next one to release (I mean right now, it's most likely a minor 0.x.0 bump but this could change once/if we go to a stable 1.0.0 version). Should the version then be something like next?

ericapisani · 2026-03-02T20:36:27Z

@Lms24

What about unreleased changes?

At the moment this script ignores them for the reason that you mentioned - we don't yet know what release the change could go out in.

Once the release is made then, as it stands right now, another PR would need to be created with the regenerated docs. This issue will still be around if we were to set the version to next, but I can see this being a better approach from the standpoint of giving users a heads up of changes that are coming in the next version.

does this overwrite pre-existing changelog entries?

Yes, but I can look into modifying this so that it preserves pre-existing entries (including manually written ones that you mentioned in another comment), while still handling the edge case of a transition where what was listed under a next version is correctly updated to the latest version number.

I assume we want to run this on every new PR, correct? Can we adjust the generate script to also execute the changelog generation script?

Should we fail CI if running this script produces changes? I think we should get this for free when we add this script to the generate command as suggested above. WDYT?

For sure we can make an adjustment to the generate script to also run this with every new PR.

When you say "producing changes", are you referring to something like a diff existing between what's in the PR vs. what the script generated?

Assuming that you are, then I think it's a great idea to fail the CI if that happens so as to ensure that the changelog is never out of date.

I'll move this PR into draft while I work through the changes and ping you once they're in! 😄

Preserve manually added descriptions, hand-curated entries, and other manual edits when re-running the changelog generation script. Previously the script would completely replace existing changelog data on every run. Add mergeChangelogs() that indexes by version, unions PR numbers, preserves existing descriptions, keeps manual-only entries, and re-sorts newest-first. Add unit tests covering edge cases. Co-Authored-By: Claude <noreply@anthropic.com>

Support unreleased changes tracked as "next" entries in attribute changelogs. When a new release tag is created, "next" entries are automatically promoted to the new version while preserving manually-added descriptions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lms24 · 2026-03-03T12:37:56Z

Yes, but I can look into modifying this so that it preserves pre-existing entries (including manually written ones that you mentioned in another comment), while still handling the edge case of a transition where what was listed under a next version is correctly updated to the latest version number.

sounds great, thanks!

When you say "producing changes", are you referring to something like a diff existing between what's in the PR vs. what the script generated?

Yes basically. I checked our Build CI job and it seems like we already fail if yarn generate causes any changes on CI. So if we run the changelog script on yarn generate we should be good!

Show the attribute changelog in the AttributeCard component, including entries with version 'next' (displayed without a 'v' prefix). Update compareVersions to handle 'next' correctly and export it for reuse in tests, removing the duplicate implementation. Co-Authored-By: Claude <noreply@anthropic.com>

Remove redundant 'next' guards in the sort comparator — compareVersions already handles 'next' correctly, making those checks dead code. Add a TODO comment noting the O(files × versions) git subprocess cost and suggesting a future batch approach using `git diff --name-only`. Co-Authored-By: Claude <noreply@anthropic.com>

…etsentry/sentry-conventions into ep/display-changelog-of-attributes-6su

Biome's noDelete lint rule flags the delete operator for performance. Since changelog is an optional field and JSON.stringify omits undefined values, the behavior is identical. Co-Authored-By: Claude <noreply@anthropic.com>

Add changelog entries with version 'next' to attributes modified by PRs #261, #264, #265, #266, and #267. This tracks upcoming changes for the next release across AI, tool, and deployment environment attributes. Co-Authored-By: Claude <noreply@anthropic.com>

ericapisani · 2026-03-03T14:41:46Z

@Lms24

I've got the changes in! Quick summary of what's changed:

Running the CI correctly fails if there are changes that are not checked in after running the generate command (see failing test in this commit)
Changelog merges now happen. Also, to make it easier to clear a changelog for an attribute, I've added a script to do so and it can be invoked via the package.json
Changes not associated with a release are tagged with next

For the future:

We may want to revisit the layout of the changelog when descriptions are being added, but leaving this alone for now because this PR is rather large.

style: Fix biome formatting and lint errors

24a4d0f

Run biome formatter across all JSON model files to inline short arrays, and replace non-null assertions with optional chaining or type casts to satisfy biome's noNonNullAssertion rule. Co-Authored-By: Claude <noreply@anthropic.com>

ericapisani marked this pull request as ready for review February 27, 2026 20:00

ericapisani requested review from a team, Lms24, cleptric, lcian, mjq and nsdeschenes as code owners February 27, 2026 20:00

Lms24 reviewed Mar 2, 2026

View reviewed changes

ericapisani marked this pull request as draft March 2, 2026 20:37

ericapisani and others added 2 commits March 2, 2026 15:46

ericapisani and others added 6 commits March 3, 2026 07:47

Merge branch 'main' into ep/display-changelog-of-attributes-6su

2367cfd

Merge branch 'ep/display-changelog-of-attributes-6su' of github.com:g…

5d8deca

…etsentry/sentry-conventions into ep/display-changelog-of-attributes-6su

fix(lint): Replace delete operator with undefined assignment

345cb4b

Biome's noDelete lint rule flags the delete operator for performance. Since changelog is an optional field and JSON.stringify omits undefined values, the behavior is identical. Co-Authored-By: Claude <noreply@anthropic.com>

ericapisani marked this pull request as ready for review March 3, 2026 14:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add changelog tracking to attribute definitions#270

feat: Add changelog tracking to attribute definitions#270
ericapisani wants to merge 10 commits intomainfrom
ep/display-changelog-of-attributes-6su

ericapisani commented Feb 27, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 27, 2026 •

edited

Loading

New Features ✨

Bug Fixes 🐛

Documentation 📚

Internal Changes 🔧

Deps

Other

Uh oh!

Lms24 left a comment

Uh oh!

Lms24 Mar 2, 2026 •

edited

Loading

Uh oh!

Lms24 Mar 2, 2026

Uh oh!

Lms24 commented Mar 2, 2026 •

edited

Loading

Uh oh!

ericapisani commented Mar 2, 2026

Uh oh!

Lms24 commented Mar 3, 2026

Uh oh!

ericapisani commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ericapisani commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's included

Screenshots

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Semver Impact of This PR

New Features ✨

Bug Fixes 🐛

Documentation 📚

Internal Changes 🔧

Deps

Other

Uh oh!

Lms24 left a comment

Choose a reason for hiding this comment

Uh oh!

Lms24 Mar 2, 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!

Lms24 Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Lms24 commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ericapisani commented Mar 2, 2026

Uh oh!

Lms24 commented Mar 3, 2026

Uh oh!

ericapisani commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ericapisani commented Feb 27, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading

Lms24 Mar 2, 2026 •

edited

Loading

Lms24 commented Mar 2, 2026 •

edited

Loading