Skip to content

chore: Update CONTRIBUTING with process and minor changes #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Lms24 wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

chore: Update CONTRIBUTING with process and minor changes #255

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2fdfe0
chore: Update CONTRIBUTING with process and minor changes
Lms24 Feb 10, 2026
529821e
Merge branch 'main' into lms/chore-update-contrib
Lms24 Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 17 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,24 @@

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

```bash
yarn install
```

# Usage
## Process

Before attributes are sent from SDKs, or attribute values change, the attributes MUST be defined 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, implement 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 ([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.
Copy link
Contributor

@dingsdax dingsdax Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

imho we should explain somewhere why the 3 day waiting period, something along the lines of

"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 every SDK that shipped it."

we could make it even more stark: "There is no urgency exception if a name feels wrong, raise it during review, not after. "

Copy link
Contributor

@dingsdax dingsdax Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

who is gonna be code owner here?
@stephanie-anderson @getsentry/sdk-seniors ?

4. Merge your PR (alternatively, code owners may merge it after review)

## Adding a new attribute
Copy link
Contributor

@dingsdax dingsdax Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest to add a paragraph about OTel alignment here. It could look something like this:

OTel Alignment

Before proposing a new attribute, check the OpenTelemetry semantic conventions registry.

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 mapping work for every integration.

If OTel doesn't define it, or the concept is Sentry-specific, set is_in_otel: false.

When in doubt, prefer OTel alignment. A Sentry-specific name can be deprecated later; an OTel-aligned name is forward-compatible by default.

@Lms24 does that make sense?


Expand Down Expand Up @@ -48,21 +57,22 @@ 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 && yarn run format` 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, you need to run `yarn run generate` to generate and format the attribute library code, which is generated from the json files stored in the `model` directory.

# Policies
## Policies

## Attributes
### Attributes
Copy link
Contributor

@dingsdax dingsdax Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we add naming rules & examples?

Naming rules:

  • Use dots as separators, not underscores (http.request.method, not http_request_method)
  • Namespace first (db.system, not system.db)
  • Keep names stable! Renames require deprecation cycles across all SDKs that adopted the attribute!


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:
- 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`.

# 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.
Expand All @@ -71,7 +81,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`.

Expand Down
Loading