Update OTel GenAI conventions skill for standalone semconv-genai repo#7519
Open
jeffhandley wants to merge 10 commits into
Open
Update OTel GenAI conventions skill for standalone semconv-genai repo#7519jeffhandley wants to merge 10 commits into
jeffhandley wants to merge 10 commits into
Conversation
The OpenTelemetry GenAI semantic conventions moved from open-telemetry/semantic-conventions (under area:gen-ai) to a dedicated repo, open-telemetry/semantic-conventions-genai. The new repo also hosts mcp, openai, anthropic, aws-bedrock, and azure-ai-inference areas, has no releases yet (CHANGELOG Unreleased is the live view), no area: labels (every PR is in scope), and a GenAI-namespaced schema URL (opentelemetry.io/schemas/gen-ai/X.Y.Z) independent of core semconv. Changes (docs-only, no source code edits): - SKILL.md: new Migration Note + Cross-repo applicability sections; rewritten Input Handling for 4 input shapes (PR refs, CHANGELOG snapshot, date range, releases); In-scope areas table with concrete external repo references; broadened search terms in PR Preflight, Mode 1 spec, Mode 2/3/5; Gotchas updated with transitional version- reference grep regex and area-aware constants bullet. - references/file-inventory.md: pre/post-migration doc-comment wording, transitional grep regex, Provider-specific instrumentation table. - references/historical-releases.md: Migration Note prepended; pointers to new repo CHANGELOG/releases/PRs. - references/change-classification.md: Areas section; Area column added to audit and PR-description tables; example anthropic row reflects cross-repo flagging. - references/implementation-patterns.md: Area placement guidance callout; Pattern 6 rewritten with pre/post wording and one-shot migration guidance. - references/implementation-procedure.md: area-aware nested class bullet. - references/review-checklist.md: §6 transitional grep + wording- migration bullet; §7 area-aware nesting; §8 provider-scope bullet with cross-repo case. - references/prompt-template.md: 4-input-shape Background block; Area column in audit table; cross-repo flagging guidance. - references/pr-description.md: title clarifies independent GenAI version; Area column in PR table; old-repo catch-up linkage. - references/testing-guide.md: Per-area test files section. For provider-specific areas not instrumented in dotnet/extensions (anthropic, aws-bedrock), the skill can be applied in the corresponding SDK repos: anthropics/anthropic-sdk-csharp and the BedrockRuntime service library of aws/aws-sdk-net. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the update-otel-genai-conventions Copilot skill documentation to reflect the OpenTelemetry GenAI semantic conventions migration from open-telemetry/semantic-conventions (area-labeled) to the standalone open-telemetry/semantic-conventions-genai repository, including expanded provider-area scope and GenAI-specific versioning.
Changes:
- Added a migration note and updated input-handling guidance to support PRs,
CHANGELOG.mdsnapshots, and date ranges fromsemantic-conventions-genai. - Introduced “area-aware” routing guidance (gen-ai vs mcp vs provider-specific areas) across the skill docs, templates, and checklists.
- Updated prompt/template and PR-description guidance to include an Area column and repo-disambiguated references.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| .github/skills/update-otel-genai-conventions/SKILL.md | Reorients the skill to semantic-conventions-genai, adds migration/cross-repo context, expands supported inputs. |
| .github/skills/update-otel-genai-conventions/references/testing-guide.md | Adds guidance on keeping tests grouped by client while accounting for upstream “area” differences. |
| .github/skills/update-otel-genai-conventions/references/review-checklist.md | Updates checklist to include wording-migration and provider/package scoping checks. |
| .github/skills/update-otel-genai-conventions/references/prompt-template.md | Updates the CCA prompt template for new input types and adds an Area column. |
| .github/skills/update-otel-genai-conventions/references/pr-description.md | Adjusts PR title/description format to GenAI versioning and adds Area column to the table shape. |
| .github/skills/update-otel-genai-conventions/references/implementation-procedure.md | Adds guidance for area-aware constant placement and wording-migration handling. |
| .github/skills/update-otel-genai-conventions/references/implementation-patterns.md | Adds “area placement guidance” section describing where changes should land by upstream area. |
| .github/skills/update-otel-genai-conventions/references/historical-releases.md | Clarifies historical entries are pre-migration and points to new repo activity sources. |
| .github/skills/update-otel-genai-conventions/references/file-inventory.md | Adds doc-comment wording migration guidance and provider-specific routing notes. |
| .github/skills/update-otel-genai-conventions/references/change-classification.md | Extends classification to multi-area + non-release inputs and updates table shapes to include Area. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
tarekgh
reviewed
May 8, 2026
Member
There was a problem hiding this comment.
A few minor observations:
-
Point-in-time version examples in the Migration Note: The inline examples
1.42.0(gen-ai) andv1.41.0(core semconv) with "at the time of writing" will silently go stale. SinceX.Y.Zis already used as the general placeholder everywhere else, consider dropping the concrete versions or pinning them with a date (e.g. "as of May 2026") so a future reader knows how old the snapshot is. -
"No releases yet" qualifier: The bullet "No releases yet in the new repo (as of this writing)" lives in a durable skill file, not a PR description. Once
semantic-conventions-genaiships its first release this will become inaccurate. A<!-- TODO: remove once first release ships -->marker (or similar) would make the staleness self-evident when it happens. -
implementation-procedure.mdstep 3, second sub-bullet: The new "Choose the correct constant location…" guidance packs a lot into one paragraph (five area categories, a concreteOpenAIClientExtensions.csexample, and the "introduce a file/class explicitly" rule). Breaking it into a mini-list or referencing the existing area-placement table inimplementation-patterns.mdinstead of restating the rules inline might make it easier to scan during implementation.
tarekgh
approved these changes
May 8, 2026
- SKILL.md Migration Note: drop point-in-time version examples (1.42.0 / v1.41.0 "at the time of writing") in favor of the X.Y.Z placeholder already used elsewhere. - SKILL.md "No releases yet" bullet: remove "as of this writing" and add a TODO marker to remove the framing once the first release ships. - implementation-procedure.md: split the dense constant-location bullet into a mini-list and link the area-placement table in implementation-patterns.md instead of restating areas inline. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tarekgh
reviewed
Jun 26, 2026
tarekgh
reviewed
Jun 26, 2026
tarekgh
reviewed
Jun 26, 2026
tarekgh
reviewed
Jun 26, 2026
- Spec URL now resolves to a 'Moved' stub; soften the claim, keep the <see href> for now, and add a TODO to retarget once a canonical URL exists - Note the schema URL (opentelemetry.io/schemas/gen-ai/X.Y.Z) is not yet published; derive the GenAI version from CHANGELOG/versions.env until then - Correct area-classification guidance: only gen-ai, mcp, openai, and aws-bedrock have a model/<area>/ registry; anthropic and azure-ai-inference are docs-only under docs/gen-ai/<provider>.md; all docs live under docs/gen-ai/ - Drop the broken schema-snapshot/ reference from Mode 1 step 4 - Note the new repo uses granular area:* labels (area:mcp, area:inference, etc.) - Apply the same corrections to the In-scope areas table header, change-classification.md, and implementation-patterns.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Self-review follow-ups found while verifying the skill against the live semantic-conventions-genai repo: - versions.env holds only the core semconv dependency (SEMCONV_VERSION, currently v1.42.0) and the Weaver version; it carries no GenAI version. Remove guidance that derived the GenAI version from versions.env and state that, until a GenAI release/schema URL exists, the update is identified by its Unreleased CHANGELOG snapshot (commit/ref/date) - file-inventory.md: drop the stale 'published spec page still resolves and renders the spec' claim; the page is now a 'Moved' stub, so keep the <see href> only until a canonical URL is published and read docs/gen-ai/ and model/<area>/ as the spec source - file-inventory.md / implementation-patterns.md: stop tying the doc-comment version to the unpublished schema URL; replace the v1.42.0 target-wording example (the core semconv version) with vX.Y.Z - pr-description.md: same version-source correction for the PR title Stop referring to a 'new repo' and an 'old repo'. Treat open-telemetry/semantic-conventions-genai as the current conventions repo and refer to open-telemetry/semantic-conventions as the consolidated repo where these conventions were previously managed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The semantic-conventions-genai CHANGELOG.md Unreleased section is empty (managed by Towncrier; fragments are compiled into it only at release time), so the live what's-new view is the changelog.d/ news fragments. - SKILL.md: Migration Note describes the Towncrier mechanism and points the what's-new view at changelog.d/ fragments; Input Handling snapshot form, Mode 1 step 4, and Mode 5 step 1 reference changelog.d/ instead of the CHANGELOG.md Unreleased section; intro lists "changelog snapshots". - references/file-inventory.md, implementation-patterns.md, pr-description.md: take the audited GenAI version from the changelog.d/ fragment snapshot. - references/historical-releases.md, prompt-template.md: link/label the changelog.d/ fragments as the snapshot source. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- references/pr-description.md Title: add a `latest` title form
("Update OpenTelemetry GenAI conventions to latest") for the unreleased
case (no release and no published schema URL), alongside the
versioned form; keep the title as `latest` and pin the changelog.d/
snapshot in the body until a version exists.
- references/pr-description.md Description: use `latest` in the Version
column and record the changelog.d/ fragment snapshot when no GenAI
version number is determined yet.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
references/pr-description.md: add an "Upstream scan tracking tables" subsection defining one shared column set for both the merged-changes table and the in-flight (open-PR) table: `| Upstream PR | Area | Change | Applicability | Status |`. The Applicability column holds the color symbol only; explanatory text goes in the separate Status column. Includes the applicability legend (implemented / aligned / watch / not applicable). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
references/pr-description.md: add guidance that the Change column must use
break opportunities (', ' or ' / ' with spaces) instead of long
unbroken /-separated runs, which browsers do not wrap and which force the
table wider than the viewport.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- pr-description.md: add an "Upstream-scan tracking PR body template" section laying out the body in order -- status note, "What this PR implements" table, the merged and in-flight applicability tables, and the otel-genai-tracking state block as the final section. - Keep the refresh procedure out of the PR body: document it in a "Refreshing the tracking PR" skill section that drives the update-otel-genai-conventions skill (Mode 1 Audit, Input Handling git log diff, change-classification, version-reference migration). - SKILL.md: point "PR Title and Description Guidance" at the full body template; note in Preflight that the tracking PR is the scan record to refresh, not a blocking duplicate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Member
Author
|
Thanks for the great feedback, @tarekgh! I continued with that theme of feedback and iterated a bit more to address a couple other places where it was unnecessarily specific about details that weren't accurate in the new repo. And then I changed the language so it doesn't emphasize the "new" repo, and it instead just uses the new repo as the current standard while referencing the previous, consolidated repo for historical audits and references. I also improved the skill's ability to recommend a PR title and body so the skill can be used to create a more presentable PR, capture the state used to produce the PR, and then repeatedly refresh an open PR as more changes land in the upstream repo. Here's the current PR now generated from this skill (from this branch): As soon as we merge this skill PR, I have an agentic workflow PR ready to go that will run daily to fully automate the creation and incremental updates for the otel changes and tracking their releases as the marker for when the PRs become Ready for Review (and don't get auto-updated after that). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The OpenTelemetry GenAI semantic conventions moved from open-telemetry/semantic-conventions (under area:gen-ai) to a dedicated repo, open-telemetry/semantic-conventions-genai. The new repo also hosts mcp, openai, anthropic, aws-bedrock, and azure-ai-inference areas, has no releases yet (CHANGELOG Unreleased is the live view), no area: labels (every PR is in scope), and a GenAI-namespaced schema URL (opentelemetry.io/schemas/gen-ai/X.Y.Z) independent of core semconv.
Changes (skill-only, no source code edits).
After applying these changes to the skill, a re-run of the skill to audit for any changes necessary correctly determined no changes are needed at this time.
Microsoft Reviewers: Open in CodeFlow