Add change log script

Author: trask

.github/agents/draft-release-notes.agent.md

@@ -1,114 +1,114 @@
 ---
-description: "Draft changelog entries for an upcoming release by running the draft-change-log-entries.sh script, then curating and inserting the results into CHANGELOG.md."
+description: "Draft changelog entries for an upcoming release by running the draft-release-notes orchestrator, then reviewing and polishing the resulting `## Unreleased` section in CHANGELOG.md."
 tools: [read, edit, execute, search]
 ---
 
 You are a release-notes drafting agent for the `opentelemetry-java-instrumentation` repository.
 
+The heavy lifting (fetching PRs, classifying them, and splicing the
+`## Unreleased` section into `CHANGELOG.md`) is done by
+`.github/scripts/draft-release-notes/draft-release-notes.py`. Your job is
+to run that orchestrator, then review the result against the local bundle
+evidence and tighten wording/grouping.
+
 Primary responsibilities:
 
-- Generate draft changelog entries by running the existing shell script.
-- Curate, categorize, and deduplicate entries.
-- Update `CHANGELOG.md` with the final entries under the `## Unreleased` section.
+- Run the orchestrator script to produce a classified, spliced changelog.
+- Review the resulting `## Unreleased` section against per-PR evidence in
+  `build/changelog-bundle/`.
+- Refine wording, grouping, and section placement in `CHANGELOG.md`.
 
-Do not stop until the changelog is updated and a summary is shown.
+Do not stop until `CHANGELOG.md` is updated and a summary is shown.
 
 ## Workflow
 
-### Phase 1: Gather Raw Entries
+### Phase 1: Run the orchestrator
 
 1. Determine the current version:
 
    ```bash
    .github/scripts/get-version.sh
    ```
 
-2. Run the draft script to generate raw entries:
+2. Run the orchestrator:
 
    ```bash
-   bash .github/scripts/draft-change-log-entries.sh
+   python3 .github/scripts/draft-release-notes/draft-release-notes.py
    ```
 
-   This script:
-   - Computes the git range since the last release tag.
-   - Queries GitHub for PRs with `breaking change` and `deprecation` labels.
-   - Scans commits for `@Deprecated` additions/removals.
-   - Groups commits by whether they touch `src/main/` files.
-   - Outputs a markdown skeleton with categorized sections.
+   If the script fails (e.g., `gh` or `copilot` CLI not available, or not
+   authenticated), report the error and stop.
 
-3. Capture the full output. If the script fails (e.g., `gh` CLI not authenticated),
-   report the error and stop.
+   This orchestrator runs three steps in order, aborting on the first
+   failure:
 
-### Phase 2: Read Prior Changelog Format
+   - `fetch.py` — computes the git range since the last release tag,
+     queries GitHub for PRs (including `breaking change` and
+     `deprecation` labeled PRs), and prepares `build/changelog-bundle/`
+     with per-PR `patch.diff`, `meta.json`, body, comments, reviews, and
+     linked issue data. Incremental by default; pass `--refetch` to
+     re-download every PR.
+   - `classify.py` — deterministic preclassify (renovate, docs/test/build-only,
+     version bumps) followed by per-PR LLM classification for everything
+     else, writing `decision.json` next to each PR's bundle. Classification
+     rules live in `.github/scripts/draft-release-notes/rules.md`.
+   - `merge.py --splice --report` — rewrites the `## Unreleased` section
+     in `CHANGELOG.md` from the per-PR decisions, preserving any existing
+     unlinked deprecation summary bullets.
 
-1. Read the top of `CHANGELOG.md` to understand the current `## Unreleased` section
-   and the format of the most recent versioned release.
-2. Note the section ordering used in prior releases. The standard order is:
+3. After the orchestrator completes, inspect the result:
 
-   - `### ⚠️ Breaking changes to non-stable APIs` (from labeled PRs and @Deprecated removals)
-   - `### 🚫 Deprecations` (from labeled PRs and @Deprecated additions)
-   - `### 🌟 New javaagent instrumentation`
-   - `### 🌟 New library instrumentation`
-   - `### 📈 Enhancements`
-   - `### 🛠️ Bug fixes`
-   - `### 🧰 Tooling`
+   ```bash
+   git diff CHANGELOG.md
+   ```
 
-### Phase 3: Curate Entries
+   Also read `build/changelog-bundle/manifest.json` to understand what was
+   fetched, and treat the per-PR bundle directories as the primary evidence
+   source when reviewing entries.
 
-Using the raw output from Phase 1, build the changelog body:
+### Phase 2: Review and refine the drafted entries
 
-1. **Breaking changes**: Take entries from the "Breaking Changes" labeled-PR section
-   and from the "Possible breaking changes (diff removes @Deprecated)" section.
-   Deduplicate by PR number.
+The orchestrator has already categorized entries into the standard sections:
 
-2. **Deprecations**: Take entries from the "Deprecations" labeled-PR section
-   and from the "Possible deprecations (diff adds @Deprecated)" section.
-   Deduplicate by PR number.
+- `### ⚠️ Breaking changes to non-stable APIs`
+- `### 🚫 Deprecations`
+- `### 🌟 New javaagent instrumentation`
+- `### 🌟 New library instrumentation`
+- `### 📈 Enhancements`
+- `### 🛠️ Bug fixes`
 
-3. **Categorize remaining commits**: For each commit in "Changes with src/main updates"
-   that was not already placed in breaking changes or deprecations, classify it into
-   one of these sections based on its commit message and changed files:
-   - **New javaagent instrumentation**: commits that add a new instrumentation module
-     (new directories under `instrumentation/`).
-   - **New library instrumentation**: commits that add new library instrumentation modules.
-   - **Enhancements**: feature additions, improvements, refactors to existing instrumentation.
-   - **Bug fixes**: commits whose message contains "fix", "bug", "regression", "correct",
-     or similar keywords.
-   - **Tooling**: changes to build scripts, CI, testing infrastructure, or tooling.
+Go through the updated `## Unreleased` block and, for each bullet:
 
-4. **Omit non-user-facing changes**: Commits in "Changes without src/main updates"
-   are typically CI, docs, or dependency updates. Exclude them from the changelog
-   unless they are clearly user-facing (e.g., documentation that ships with the release).
+1. Open the corresponding PR's bundle directory under
+   `build/changelog-bundle/prs/<N>/` and read `decision.json`, `meta.json`,
+   `body.md`, and `patch.diff` as needed to confirm the entry is accurate.
 
-5. Format each entry as:
+2. Tighten wording so each bullet reads as a concise user-facing change,
+   matching the style of prior releases in `CHANGELOG.md`.
 
-   ```
-   - Short description of the change
-     ([#NNNN](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/NNNN))
-   ```
+3. Move entries between sections if the classification looks wrong based
+   on the evidence. Prefer editing `CHANGELOG.md` directly; if a decision
+   looks systematically wrong, note it for a future update to `rules.md`.
 
-   When multiple PRs relate to the same logical change, group them:
+4. Group related PRs that describe the same logical change:
 
    ```
    - Short description of the change
      ([#AAAA](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/AAAA),
       [#BBBB](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/BBBB))
    ```
 
-6. Omit empty sections entirely.
+5. Remove empty sections entirely.
+
+6. Preserve any unlinked deprecation summary bullets that `merge.py`
+   carried forward under `### 🚫 Deprecations`.
 
-### Phase 4: Update CHANGELOG.md
+### Phase 3: Confirm
 
-1. Read `CHANGELOG.md`.
-2. Locate the `## Unreleased` section (everything between `## Unreleased` and the
-   next `## Version` heading).
-3. Replace the content of the `## Unreleased` section with the curated entries,
-   preserving a blank line after `## Unreleased` and before the next `## Version`.
-4. Write the updated file.
-5. Show a confirmation message:
+Show a confirmation message:
 
-   > ✅ Updated CHANGELOG.md with draft entries for version `<version>`.
-   > Run `git diff CHANGELOG.md` to review the changes.
+> ✅ Updated CHANGELOG.md with draft entries for version `<version>`.
+> Run `git diff CHANGELOG.md` to review the changes.
 
 ## Rules
 
@@ -117,6 +117,7 @@ Using the raw output from Phase 1, build the changelog body:
 - Preserve the exact heading format (`## Unreleased`) — do not add a date or version number.
   The version heading is set later during the release process.
 - Use the same markdown formatting conventions as prior releases in the file.
-- If `gh` CLI is unavailable or not authenticated, fall back to git-only analysis
-  (skip labeled-PR extraction) and warn the user that breaking-change and deprecation
-  labels could not be checked.
+- Do not re-run `fetch.py`, `classify.py`, or `merge.py` directly; drive
+  them through `draft-release-notes.py` so the three steps stay in sync.
+- If a PR's classification looks wrong, fix the bullet in `CHANGELOG.md`
+  rather than hand-editing `decision.json`.

.github/scripts/draft-change-log-entries.sh

@@ -1,5 +1,8 @@
 #!/bin/bash -e
 
+# this has mostly been replaced by .github/scripts/draft-release-notes/draft-release-notes.py
+# keeping this around as a backup since that script relies on Copilot CLI
+
 version=$("$(dirname "$0")/get-version.sh")
 
 if [[ $version =~ ([0-9]+)\.([0-9]+)\.0 ]]; then
@@ -23,115 +26,29 @@ else
   range="v$major.$((minor - 1)).0..HEAD"
 fi
 
-echo "# Changelog"
-echo
 echo "## Unreleased"
 echo
-
-"$(dirname "$0")/extract-labeled-prs.sh" "$range"
-
+echo "### Migration notes"
+echo
+echo
 echo "### 🌟 New javaagent instrumentation"
 echo
+echo
 echo "### 🌟 New library instrumentation"
 echo
+echo
 echo "### 📈 Enhancements"
 echo
+echo
 echo "### 🛠️ Bug fixes"
 echo
+echo
 echo "### 🧰 Tooling"
 echo
 
-# Group commits by file type and @Deprecated detection
-declare -A src_main_commits
-declare -A no_src_main_commits
-declare -A deprecated_added_commits
-declare -A deprecated_removed_commits
-
-format_commit_msg() {
-  git log --format=%s -n 1 "$1" | sed -E 's, *\(#([0-9]+)\)$,\n  ([#\1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/\1)),'
-}
-
-while IFS= read -r commit_hash; do
-  files=$(git diff-tree --no-commit-id --name-only -r "$commit_hash")
-
-  has_src_main=false
-
-  while IFS= read -r file; do
-    if [[ $file =~ /src/main/ ]] && [[ ! $file =~ ^smoke-tests/ ]] && [[ ! $file =~ ^smoke-tests-otel-starter/ ]] && [[ ! $file =~ /testing/ ]] && [[ ! $file =~ -testing/ ]] && [[ ! $file =~ ^instrumentation-docs/ ]]; then
-      has_src_main=true
-      break
-    fi
-  done <<< "$files"
-
-  commit_msg=$(git log --format=%s -n 1 "$commit_hash" | sed -E 's, *\(#([0-9]+)\)$,\n  ([#\1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/\1)),')
-
-  # Check diff for @Deprecated additions/removals in src/main Java files
-  # Count added vs removed to distinguish real changes from moves/refactors
-  diff_output=$(git diff-tree -p "$commit_hash" -- '*/src/main/**/*.java' 2>/dev/null || true)
-
-  added_count=$(echo "$diff_output" | grep -cP '^\+(?!\+).*@Deprecated' || true)
-  removed_count=$(echo "$diff_output" | grep -cP '^-(?!-).*@Deprecated' || true)
-
-  # Net new @Deprecated annotations = new deprecation
-  if [[ $added_count -gt $removed_count ]]; then
-    deprecated_added_commits["$commit_hash"]=1
-  fi
-  # Net removed @Deprecated annotations = removed deprecated API (breaking)
-  if [[ $removed_count -gt $added_count ]]; then
-    deprecated_removed_commits["$commit_hash"]=1
-  fi
-
-  # Categorize commit
-  if [[ $has_src_main == true ]]; then
-    src_main_commits["$commit_hash"]="$commit_msg"
-  else
-    no_src_main_commits["$commit_hash"]="$commit_msg"
-  fi
-done < <(git log --reverse --perl-regexp --author='^(?!renovate\[bot\] )' --pretty=format:"%H" "$range")
-
-# Output @Deprecated-based breaking changes (removed @Deprecated = removed deprecated API)
-if [[ ${#deprecated_removed_commits[@]} -gt 0 ]]; then
-  echo "#### Possible breaking changes (diff removes @Deprecated)"
-  echo
-  for commit_hash in $(git log --reverse --perl-regexp --author='^(?!renovate\[bot\] )' --pretty=format:"%H" "$range"); do
-    if [[ -n ${deprecated_removed_commits[$commit_hash]} ]]; then
-      echo "- $(format_commit_msg "$commit_hash")"
-    fi
-  done
-  echo
-fi
-
-# Output @Deprecated-based deprecations (added @Deprecated = new deprecation)
-if [[ ${#deprecated_added_commits[@]} -gt 0 ]]; then
-  echo "#### Possible deprecations (diff adds @Deprecated)"
-  echo
-  for commit_hash in $(git log --reverse --perl-regexp --author='^(?!renovate\[bot\] )' --pretty=format:"%H" "$range"); do
-    if [[ -n ${deprecated_added_commits[$commit_hash]} ]]; then
-      echo "- $(format_commit_msg "$commit_hash")"
-    fi
-  done
-  echo
-fi
-
-# Output grouped commits
-if [[ ${#src_main_commits[@]} -gt 0 ]]; then
-  echo "#### Changes with src/main updates"
-  echo
-  for commit_hash in $(git log --reverse --perl-regexp --author='^(?!renovate\[bot\] )' --pretty=format:"%H" "$range"); do
-    if [[ -n ${src_main_commits[$commit_hash]} ]] && [[ -z ${deprecated_added_commits[$commit_hash]} ]] && [[ -z ${deprecated_removed_commits[$commit_hash]} ]]; then
-      echo "- $(format_commit_msg "$commit_hash")"
-    fi
-  done
-  echo
-fi
-
-if [[ ${#no_src_main_commits[@]} -gt 0 ]]; then
-  echo "#### Changes without src/main updates"
-  echo
-  for commit_hash in $(git log --reverse --perl-regexp --author='^(?!renovate\[bot\] )' --pretty=format:"%H" "$range"); do
-    if [[ -n ${no_src_main_commits[$commit_hash]} ]] && [[ -z ${deprecated_added_commits[$commit_hash]} ]] && [[ -z ${deprecated_removed_commits[$commit_hash]} ]]; then
-      echo "- $(format_commit_msg "$commit_hash")"
-    fi
-  done
-  echo
-fi
+git log --reverse \
+        --perl-regexp \
+        --author='^(?!renovate\[bot\] )' \
+        --pretty=format:"- %s" \
+        "$range" \
+  | sed -E 's,\(#([0-9]+)\)$,\n  ([#\1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/\1)),'