From db3373a18137a5ca438b7f049024b5df53d5873e Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 10 Feb 2026 14:24:56 +0100 Subject: [PATCH 1/5] chore: Update CONTRIBUTING with process and minor changes --- CONTRIBUTING.md | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 671c1067..79c0b525 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Running this repo requires the usage of [volta](https://volta.sh/). See instructions on installing volta on their documentation [here](https://docs.volta.sh/guide/getting-started). The repo requires Node v22 or higher to run. -# Setup +## Setup To install required dependencies, run `yarn install`. @@ -10,10 +10,33 @@ To install required dependencies, run `yarn install`. yarn install ``` -# Usage +## Process + +Before attributes are sent from SDKs, or attribute values or definitions change, the attributes MUST be defined or updated in this repo. If the convention you need doesn't exist yet, open a PR there to propose it. Only after the convention has been merged, ship it in an SDK. This ensures all SDKs use consistent naming and semantics. + +The merge process for sentry-conventions PRs: + +1. Open a PR with the proposed convention change ([Adding an Attribute](#adding-a-new-attribute)). +2. Get an approval from at least one code owner. +3. Wait for at least 3 business days after the first approval to give other code owners a chance to review. + This grace period exists because attribute names, once shipped in an SDK release, are effectively permanent. If a bad name gets adopted by even one SDK, fixing it requires a deprecation cycle across the SDK(s) that shipped it and the Sentry backend. +4. Merge your PR (alternatively, code owners may merge it after review) ## Adding a new attribute +> [!IMPORTANT] +> ### OTel Alignment +> +> Before proposing a new attribute, check the [OpenTelemetry semantic conventions registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/). +> +> If OTel already defines the attribute: +> - Use the OTel name and type. Set `is_in_otel: true`. +> - Do not create a Sentry-specific synonym!. Diverging from OTel for the same concept creates more confusion and work than value. +> +> If OTel doesn't define it, or the concept is Sentry-specific, set `is_in_otel: > false`. +> +> When in doubt, prefer OTel alignment. Sentry conventions should only extend OTel, not diverge from it. + Run `yarn run create:attribute` to create a new attribute. This will prompt you to enter information about the attribute. There are two modes: - Interactive mode: This will prompt you to enter information about the attribute. @@ -48,13 +71,14 @@ Remember to run `yarn run generate` after editing or creating a `name` conventio ## Code and Docs Generation -After you edit an attribute or add a new one, you should run `yarn run generate` to generate and format the code and docs, which are generated from the json files stored in the `model` directory. +After you edit an attribute or add a new one, run `yarn run generate` to generate and format the code and docs, which are generated from the json files stored in the `model` directory. -# Policies +## Policies -## Attributes +### Attributes Here's a list of policies that any newly added attributes MUST follow. Most of these are automatically enforced by the test suite. + - The attribute MUST be namespaced. Example: `nextjs.function_id`, not `function_id`. - The `pii` field in the attribute definition MUST be `maybe` or `true` (if the attribute can contain sensitive data). It SHOULD be `false` only if scrubbing the attribute value for PII would potentially break product features. For example, `sentry.replay_id` should have `pii` set to `false`. - When an attribute is added that deprecates an old one: @@ -62,7 +86,7 @@ Here's a list of policies that any newly added attributes MUST follow. Most of t - For both the new and the old attribute, and any existing aliases of the old attribute, the new and old names MUST be added to the `aliases` list. - The deprecation status of the old one SHOULD be set to `backfill` for at least 90 days, and then set to `normalize`. -# Testing +## Testing This repo uses [Vitest](https://vitest.dev/) for testing. To run the tests, run `yarn test`. The tests enforce logical correctness as well as policies that the model should follow. @@ -71,7 +95,7 @@ The tests enforce logical correctness as well as policies that the model should yarn test ``` -# Linting +## Linting This repo uses [Biome](https://biome.sh/) and other platform-specific tools for linting. To run the linting, run `yarn lint`. From d99f6335696931202b8e62a4359da4f0872e59a1 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 15 Apr 2026 10:37:53 +0200 Subject: [PATCH 2/5] add code review suggestions --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79c0b525..eab73f5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ The merge process for sentry-conventions PRs: > - Use the OTel name and type. Set `is_in_otel: true`. > - Do not create a Sentry-specific synonym!. Diverging from OTel for the same concept creates more confusion and work than value. > -> If OTel doesn't define it, or the concept is Sentry-specific, set `is_in_otel: > false`. +> If OTel doesn't define it, or the concept is Sentry-specific, set `is_in_otel: false`. > > When in doubt, prefer OTel alignment. Sentry conventions should only extend OTel, not diverge from it. @@ -80,6 +80,9 @@ After you edit an attribute or add a new one, run `yarn run generate` to generat Here's a list of policies that any newly added attributes MUST follow. Most of these are automatically enforced by the test suite. - The attribute MUST be namespaced. Example: `nextjs.function_id`, not `function_id`. +- Use dots as separators for namespaces and logical grouoing, not underscores (`http.request.method`, not `http_request_method`) +- Use `snake_case` for multi-word names (`browser.web_vital.ttfb.request_time`, not `browser.webVital.ttfb.request-time`) +- Namespace first (`db.system`, not `system.db`) - The `pii` field in the attribute definition MUST be `maybe` or `true` (if the attribute can contain sensitive data). It SHOULD be `false` only if scrubbing the attribute value for PII would potentially break product features. For example, `sentry.replay_id` should have `pii` set to `false`. - When an attribute is added that deprecates an old one: - The old one should be marked as deprecated, and it MUST point to the new one using the `deprecation.replacement` field. From c7867f087bc42edea4d6ffb3e02943f595db055a Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 15 Apr 2026 10:39:26 +0200 Subject: [PATCH 3/5] one more --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eab73f5e..936c32c7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,6 +88,7 @@ Here's a list of policies that any newly added attributes MUST follow. Most of t - The old one should be marked as deprecated, and it MUST point to the new one using the `deprecation.replacement` field. - For both the new and the old attribute, and any existing aliases of the old attribute, the new and old names MUST be added to the `aliases` list. - The deprecation status of the old one SHOULD be set to `backfill` for at least 90 days, and then set to `normalize`. +- Prefer keeping names stable. Renames require deprecation cycles across all SDKs that adopted the attribute! ## Testing From 330513742c47147eec7409d4a798ededa68b1838 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 15 Apr 2026 10:40:51 +0200 Subject: [PATCH 4/5] more stark --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 936c32c7..56d45a5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,9 @@ The merge process for sentry-conventions PRs: 1. Open a PR with the proposed convention change ([Adding an Attribute](#adding-a-new-attribute)). 2. Get an approval from at least one code owner. 3. Wait for at least 3 business days after the first approval to give other code owners a chance to review. - This grace period exists because attribute names, once shipped in an SDK release, are effectively permanent. If a bad name gets adopted by even one SDK, fixing it requires a deprecation cycle across the SDK(s) that shipped it and the Sentry backend. + This grace period exists because attribute names, once shipped in an SDK release, are effectively permanent. If a bad name gets adopted by even one SDK, fixing it requires a deprecation cycle across the SDK(s) that shipped it and the Sentry backend. + There is no urgency exception. + If a name feels wrong, raise it during review, not after. 4. Merge your PR (alternatively, code owners may merge it after review) ## Adding a new attribute From 329fb2acb91310d44b57e6f3f300e7c1962d9708 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 15 Apr 2026 10:50:27 +0200 Subject: [PATCH 5/5] add release instructions --- CONTRIBUTING.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56d45a5b..c093e23b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,15 @@ Remember to run `yarn run generate` after editing or creating a `name` conventio ## Code and Docs Generation -After you edit an attribute or add a new one, run `yarn run generate` to generate and format the code and docs, which are generated from the json files stored in the `model` directory. +After you edit an attribute or add a new one, run `yarn run generate` to generate and format the code, which are generated from the json files stored in the `model` directory. + +Docs are generated on every PR merge. + +The generated code packages can be published to package repositories (currently npm and pypi) at any time by creating a new release: + +1. Trigger the [Release](https://github.com/getsentry/sentry-conventions/actions/workflows/release.yml) Github workflow. Define the version to be released. Usually, assuming any attribute changes are part of the release, that's a new minor version. We're intentionally on major version `0.x` to allow breaking changes in minor releases for now. +2. Head over to [`getsentry/publish`](https://github.com/getsentry/publish/issues) and wait for a new issue to appear. Ensure the changes look correct and all CI checks have passed +3. Add the `accept` label. A bot will start the release workflow. Wait for the release to complete. ## Policies