Skip to content

Add 'how to define spans' meta-guidance - #3240

Merged
joaopgrassi merged 9 commits into
open-telemetry:mainfrom
lmolkova:how-to-define-spans
Feb 4, 2026
Merged

joaopgrassi merged 9 commits into
open-telemetry:mainfrom
lmolkova:how-to-define-spans

Conversation

@lmolkova

@lmolkova lmolkova commented Jan 3, 2026

Copy link
Copy Markdown
Member

Fixes #1853

Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
@lmolkova
lmolkova force-pushed the how-to-define-spans branch from 0b17b67 to a2914f1 Compare January 9, 2026 21:34
@lmolkova lmolkova added the Skip Changelog Label to skip the changelog check label Jan 9, 2026
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
@kamphaus

Copy link
Copy Markdown
Contributor

Is there a reason not to include a changelog entry?

#2232 was listed as a doc enhancement.

@lmolkova
lmolkova force-pushed the how-to-define-spans branch from 3dbd5dd to 15ef301 Compare January 16, 2026 23:57
@lmolkova

lmolkova commented Jan 17, 2026 •

Copy link
Copy Markdown
Member Author

Is there a reason not to include a changelog entry?

#2232 was listed as a doc enhancement.

good question. In my view changelog is a summary of things that have changed that's relevant to consumers. This doc does not change any conventions and users don't need to be notified. In this sense, it's similar to CI fixes and internal docs updates. As you noticed we're not consistent and some PRs include changelog even when they don't change anything for consumers.

@kamphaus

Copy link
Copy Markdown
Contributor

Is there a reason not to include a changelog entry?
#2232 was listed as a doc enhancement.

good question. In my view changelog is a summary of things that have changed that's relevant to consumers. This doc does not change any conventions and users don't need to be notified. In this sense, it's similar to CI fixes and internal docs updates. As you noticed we're not consistent and some PRs include changelog even when they don't change anything for consumers.

I feel that we could count writers of decentralized semantic conventions as consumers.
Any enhancement to the how-to-write-conventions would be of interest to them.

@github-actions github-actions Bot added the enhancement New feature or request label Jan 23, 2026
@lmolkova

Copy link
Copy Markdown
Member Author

@kamphaus make sense, I added the changelog. Would you be interested in updating contrib.md to document this policy - https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md#when-to-add-a-changelog-entry ?

@kamphaus

Copy link
Copy Markdown
Contributor

@kamphaus make sense, I added the changelog. Would you be interested in updating contrib.md to document this policy - https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md#when-to-add-a-changelog-entry ?

Done: #3329

@joaopgrassi joaopgrassi moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Jan 30, 2026
Comment thread docs/how-to-write-conventions/README.md Resolved
Comment thread docs/how-to-write-conventions/README.md Resolved
lmolkova and others added 2 commits January 30, 2026 17:59
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
@joaopgrassi joaopgrassi moved this from Awaiting codeowners approval to Needs More Approval in Semantic Conventions Triage Feb 2, 2026
@trask trask moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Feb 2, 2026
@joaopgrassi
joaopgrassi added this pull request to the merge queue Feb 4, 2026
Merged via the queue into open-telemetry:main with commit 9e37bc2 Feb 4, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request Skip Changelog Label to skip the changelog check

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

SemConv guidance: document how to define spans

5 participants