Update changelog for upcoming release

Author: trask

.github/skills/draft-release-notes/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: draft-release-notes
+description: Draft the Unreleased section of CHANGELOG.md by running .github/scripts/draft-change-log-entries.sh, classifying each PR from its real diff, and producing clean user-facing entries. Use when asked to prepare, update, or clean up the Unreleased section of CHANGELOG.md.
+---
+
+# Draft Release Notes Skill
+
+This skill turns the raw output of `.github/scripts/draft-change-log-entries.sh`
+into a curated `## Unreleased` section in `CHANGELOG.md`.
+
+The rules below are baked in from previous drafting passes on this repo. Follow
+them directly rather than re-deriving them.
+
+## When to Use
+
+- Asked to draft, refresh, or clean up the `## Unreleased` section of
+  `CHANGELOG.md`.
+- Asked to categorize a batch of recent PRs into release-note sections.
+- Asked to decide whether a specific PR is a breaking change, deprecation,
+  enhancement, or bug fix.
+
+## Prerequisites
+
+- `gh` CLI authenticated (needed for label-based extraction inside the script
+  and for inspecting individual PR diffs).
+- `git` available with local branches up to date.
+- You are operating on the repository root.
+
+## Section Order
+
+Use exactly this order. Omit any section that ends up empty.
+
+1. `### ⚠️ Breaking changes to non-stable APIs`
+2. `### 🚫 Deprecations`
+3. `### 🌟 New javaagent instrumentation`
+4. `### 🌟 New library instrumentation`
+5. `### 📈 Enhancements`
+6. `### 🛠️ Bug fixes`
+7. `### 🧰 Tooling` (only if it carries user-facing tooling changes)
+
+## Workflow
+
+### 1. Generate the raw draft
+
+```bash
+.github/scripts/draft-change-log-entries.sh | tee out
+```
+
+The script:
+
+- Computes the commit range since the last release tag.
+- Pulls PRs labeled `breaking change` and `deprecation` via `gh`.
+- Flags commits whose diff adds or removes `@Deprecated` on `src/main` files.
+- Groups remaining commits by whether they touch `src/main/`.
+
+Keep the `out` file around for the whole pass; you will re-read it per PR.
+Delete it at the end.
+
+If the script fails (usually `gh` not authenticated), fix that before
+continuing. Do not hand-roll the list.
+
+### 2. Read the current CHANGELOG
+
+Read the top of `CHANGELOG.md` and identify the `## Unreleased` block. Only
+this block may be modified. Never touch prior versioned releases.
+
+If the block is completely empty, start from an empty set of entries. If it
+already has content, treat each existing bullet as a provisional classification
+to re-verify against the draft output.
+
+### 3. Classify each PR from its real diff
+
+For every PR number in the draft output, decide its section from the diff,
+not from the PR title. Use these signals:
+
+- `gh pr view <NNNN> --json title,files --jq '{title, files: [.files[].path]}'`
+- `gh pr diff <NNNN> --patch` (use this when the local squash commit is empty
+  or when you need to read actual code changes)
+- `git log --grep '#NNNN'` and `git show <sha>` for local history
+
+Then apply the rules in the next section.
+
+### 4. Apply the classification rules
+
+#### Breaking changes to non-stable APIs
+
+Put under this section when the PR removes or changes a public method,
+interface, class, or signature in a non-stable (`-alpha`) module or in an
+`internal` / experimental extension API.
+
+- The `#### Possible breaking changes (diff removes @Deprecated)` block in the
+  draft output is the strongest signal.
+- Also inspect PRs that touch `javaagent-extension-api` and any
+  `*/internal/**` package — removing a `default` method from an internal
+  experimental interface is a breaking change to a non-stable API even if the
+  class is marked `internal`.
+- Example from a prior pass: PR #17812 removed
+  `ExperimentalInstrumentationModule.isIndyReady()` from the internal
+  experimental extension API. That belonged in Breaking changes even though
+  its per-module overrides looked like cleanup.
+
+Entries here describe what was removed/changed and where, not the motivation.
+
+#### Deprecations
+
+Put under this section when the PR deprecates user-facing API or config
+without removing it.
+
+- The `#### Possible deprecations (diff adds @Deprecated)` block in the draft
+  output is the strongest signal for Java API deprecations.
+- Configuration property renames always belong here, not in Enhancements.
+  Name the **old** and **new** user-facing property and/or declarative YAML
+  key. Use the flat system property name in the user-facing text, because that
+  is what most users configure.
+- When the same PR renames both a builder method and a property, describe
+  both in one bullet.
+
+See `.github/agents/knowledge/api-deprecation-policy.md` and
+`.github/agents/knowledge/config-property-stability.md` for the authoritative
+policy. The one-line summary:
+
+- Stable property/API: may be deprecated in any minor; may only be removed in
+  a major.
+- Experimental property (name contains `experimental` or YAML key ends with
+  `/development`): may be deprecated and removed in a later release.
+
+#### New javaagent instrumentation / New library instrumentation
+
+Only use when the PR adds a brand-new instrumentation module under
+`instrumentation/<name>/javaagent/**` or `instrumentation/<name>/library/**`.
+Renaming or extracting an existing module does not count.
+
+Confirm via the PR's file list:
+
+- New module: a new `instrumentation/<name>/javaagent/build.gradle.kts` (or
+  `library/build.gradle.kts`) together with new source files and a
+  `settings.gradle.kts` entry.
+- Rename: a module path change with no brand-new coverage of a library.
+
+If no PRs fit, delete both empty section headers from the Unreleased block
+before finalizing.
+
+#### Enhancements
+
+User-visible feature additions, new attributes, new config flags, new
+stable-semconv support, or observable behavior changes gated on a new or
+existing flag.
+
+Examples that belong here: adding a new attribute on a span, adding a stable
+`db.system.name` emission, adding a new config toggle under `v3_preview`,
+adding schema URL on an instrumenter, optimizing an observable hot path.
+
+#### Bug fixes
+
+Observable bug fixes: wrong attribute values, missing spans, NPEs, memory
+leaks, crashes, latest-dep compatibility fixes that users would notice.
+
+Prefer describing the user-visible symptom or the concrete remediation (for
+example "Prevent duplicate OpenTelemetry Logback appenders in Spring starter"
+rather than "fix duplicate appender registration").
+
+#### Omit entirely
+
+Do **not** create entries for:
+
+- Pure refactoring or code cleanup.
+- Style-only changes (naming conventions, `final` changes, null comparisons).
+- Test-only changes, cross-testing, moving tests out of default packages.
+- Muzzle-only CI fixes with no runtime behavior change.
+- Renames of internal fields, internal packages, or internal helpers.
+- Gradle / build-script internal tweaks that do not change published artifacts
+  or published behavior.
+- `renovate[bot]` dependency bumps (the script already filters them; keep
+  them filtered).
+
+If in doubt, re-read the PR diff. Entries in Unreleased must describe an
+observable change that a user could notice.
+
+### 5. Wording rules
+
+- One sentence per bullet. Imperative or descriptive, consistent with prior
+  releases.
+- Name concrete user-facing surfaces: flag names, property names, class names,
+  attribute names. Prefer flag values over internal mechanisms. For semconv
+  opt-ins, cite the actual flag like
+  `otel.semconv-stability.opt-in=messaging`, not "via SemconvStability".
+- Use backticks for config keys, property names, attributes, and class/method
+  names.
+- Do not describe implementation details ("refactored", "moved", "simplified")
+  unless that is the user-visible change itself.
+- Do not credit authors.
+
+### 6. Link format
+
+Each entry ends with the PR link on its own line, two-space indented:
+
+```markdown
+- Short user-facing description
+  ([#NNNN](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/NNNN))
+```
+
+If multiple PRs share one logical change, group them on one trailing line:
+
+```markdown
+- Short user-facing description
+  ([#AAAA](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/AAAA),
+   [#BBBB](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/BBBB))
+```
+
+Some Deprecations bullets intentionally have no PR link (they summarize
+multiple earlier renames). Leave those as-is if they already exist.
+
+### 7. Sort order inside each section
+
+Within each populated section, sort PR-linked entries by ascending PR number.
+Unlinked bullets (if any) stay at the top of their section in their current
+order.
+
+After reordering, do a readback of the whole `## Unreleased` block and
+visually confirm monotonic PR numbers in each section.
+
+### 8. Handling tricky cases
+
+- **Empty local squash commit**: if `git show` for a PR is empty, use
+  `gh pr diff <NNNN> --patch` to get the real diff.
+- **PR that touches both user-facing behavior and internal cleanup**:
+  classify on the user-facing part. Ignore the cleanup aspect.
+- **PR that renames a config property**: always Deprecations, never
+  Enhancements. Name both old and new property. Remove any stray Enhancements
+  bullet that duplicates it.
+- **PR that looks like an Enhancement but only changes internal wiring**:
+  omit.
+- **Property rename bullets with no PR link**: keep in Deprecations at the top
+  of that subsection if already present; do not invent PR links for them.
+
+### 9. Finalize
+
+1. Delete any Unreleased sub-section that ended up empty.
+2. Re-read the full `## Unreleased` block end-to-end and sanity-check:
+   - Section order matches the canonical order above.
+   - Each populated section is PR-number-sorted.
+   - No cleanup/refactor-only bullets slipped in.
+   - Config renames appear exactly once, under Deprecations.
+   - Every bullet names a concrete user-facing surface.
+3. Run `git diff CHANGELOG.md` to confirm only `## Unreleased` changed.
+4. Delete the temporary `out` file.
+5. Summarize counts per section for the user (for example "Breaking: 1,
+   Deprecations: 9, Enhancements: 18, Bug fixes: 31").
+
+## Reference Knowledge
+
+- `.github/agents/knowledge/api-deprecation-policy.md` — deprecate-then-remove
+  timing, stable vs alpha rules, required Javadoc/CHANGELOG coverage.
+- `.github/agents/knowledge/config-property-stability.md` — stable vs
+  experimental property policy, deprecation communication, naming
+  conventions.
+- `.github/scripts/draft-change-log-entries.sh` — the source of the raw
+  draft. Read it if you need to understand exactly what the sub-sections
+  mean.