Automation for tracking breaking changes

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

@@ -28,6 +28,17 @@ echo
 echo "### Migration notes"
 echo
 echo
+
+# Add breaking changes section
+if [[ -z $range ]]; then
+  breaking_range="HEAD"
+else
+  breaking_range="$range"
+fi
+
+"$(dirname "$0")/extract-breaking-changes.sh" "$breaking_range"
+echo
+
 echo "### 🌟 New javaagent instrumentation"
 echo
 echo

.github/scripts/extract-breaking-changes.sh

@@ -0,0 +1,46 @@
+#!/bin/bash -e
+
+# This script extracts PRs with "breaking change" label for the given version range
+# Usage: extract-breaking-changes.sh [git-range]
+# If no range is provided, it uses HEAD
+
+range="${1:-HEAD}"
+
+if [[ "$range" == "HEAD" ]]; then
+  # Get all commits from HEAD
+  commits=$(git log --reverse --pretty=format:"%H %s" HEAD)
+else
+  # Get commits in the specified range
+  commits=$(git log --reverse --pretty=format:"%H %s" "$range")
+fi
+
+echo "### ⚠️ Breaking Changes"
+echo
+
+breaking_changes_found=false
+
+# Process each commit to find PRs with breaking change labels
+while IFS= read -r line; do
+  if [[ -z "$line" ]]; then
+    continue
+  fi
+
+  # Extract PR number from commit message
+  if [[ $line =~ \(#([0-9]+)\)$ ]]; then
+    pr_number="${BASH_REMATCH[1]}"
+    commit_subject=$(echo "$line" | cut -d' ' -f2- | sed 's/ (#[0-9]*)$//')
+
+    # Check if this PR has the breaking change label using GitHub CLI
+    if gh pr view "$pr_number" --json labels --jq '.labels[].name' 2>/dev/null | grep -q "breaking change"; then
+      breaking_changes_found=true
+      echo "- $commit_subject"
+      echo "  ([#$pr_number](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/$pr_number))"
+      echo
+    fi
+  fi
+done <<< "$commits"
+
+if [[ "$breaking_changes_found" == "false" ]]; then
+  echo "*No breaking changes in this release.*"
+  echo
+fi

.github/scripts/format-release-notes.sh

@@ -0,0 +1,41 @@
+#!/bin/bash -e
+
+# Format changelog section for GitHub release notes
+# Usage: format-release-notes.sh <changelog_section_file> <output_file>
+
+changelog_section="$1"
+output_file="$2"
+
+if [[ -z "$changelog_section" || -z "$output_file" ]]; then
+  echo "Usage: format-release-notes.sh <changelog_section_file> <output_file>"
+  exit 1
+fi
+
+if [[ ! -f "$changelog_section" ]]; then
+  echo "Error: Changelog section file '$changelog_section' not found"
+  exit 1
+fi
+
+# Generate all output and redirect to file at once
+{
+  # Add breaking changes section if it exists
+  if grep -q "### ⚠️ Breaking Changes" "$changelog_section"; then
+    cat << 'EOF'
+
+## 🚨 IMPORTANT: Breaking Changes
+
+This release contains breaking changes. Please review the changes below:
+
+EOF
+
+    # Extract breaking changes section, format for release notes
+    sed -n '/### ⚠️ Breaking Changes/,/^### /p' "$changelog_section" | sed '$d' | \
+      perl -0pe 's/(?<!\n)\n *(?!\n)(?![-*] )(?![1-9]+\. )/ /g'
+
+    echo -e "\n---\n"
+  fi
+
+  # the complex perl regex is needed because markdown docs render newlines as soft wraps
+  # while release notes render them as line breaks
+  perl -0pe 's/(?<!\n)\n *(?!\n)(?![-*] )(?![1-9]+\. )/ /g' "$changelog_section"
+} > "$output_file"

.github/workflows/breaking-change-pr-comment.yml

@@ -0,0 +1,60 @@
+name: Breaking Change PR Comment
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  comment-on-breaking-change:
+    if: contains(github.event.label.name, 'breaking change')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            // Check if we've already commented about breaking changes
+            const botComment = comments.find(comment => 
+              comment.user.login === 'github-actions[bot]' && 
+              comment.body.includes('⚠️ Breaking Change Documentation Required')
+            );
+
+            if (!botComment) {
+              const commentBody = [
+                "## ⚠️ Breaking Change Documentation Required",
+                "",
+                "This PR has been labeled as a **breaking change**. Please ensure you provide the following information:",
+                "",
+                "### Migration Notes Required",
+                "Please add detailed migration notes to help users understand:",
+                "- What is changing and why",
+                "- How to update their code/configuration", 
+                "- Any alternative approaches if applicable",
+                "- Code examples showing before/after usage",
+                "",
+                "### Checklist",
+                "- [ ] Migration notes added to the PR description or as a comment",
+                "- [ ] Breaking change is documented in the changelog entry for the next release",
+                "- [ ] Consider if this change requires a major version bump",
+                "",
+                "Your migration notes will be included in the release notes to help users upgrade smoothly. The more detailed and helpful they are, the better the user experience will be.",
+                "",
+                "---",
+                "*This comment was automatically generated because the `breaking change` label was applied to this PR.*"
+              ].join("\n");
+
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: commentBody
+              });
+            }

.github/workflows/release.yml

@@ -153,10 +153,8 @@ jobs:
           sed -n "0,/^## Version $VERSION /d;/^## Version /q;p" CHANGELOG.md \
             > /tmp/CHANGELOG_SECTION.md
 
-          # the complex perl regex is needed because markdown docs render newlines as soft wraps
-          # while release notes render them as line breaks
-          perl -0pe 's/(?<!\n)\n *(?!\n)(?![-*] )(?![1-9]+\. )/ /g' /tmp/CHANGELOG_SECTION.md \
-            >> /tmp/release-notes.txt
+          # Format changelog section for release notes (includes breaking changes handling)
+          .github/scripts/format-release-notes.sh /tmp/CHANGELOG_SECTION.md /tmp/release-notes.txt
 
           # conditional block not indented because of the heredoc
           if [[ $VERSION == *.0 ]]; then

CONTRIBUTING.md

@@ -6,6 +6,8 @@ Before submitting new features or changes to current functionality, it is recomm
 [open an issue](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/new)
 and discuss your ideas or propose the changes you wish to make.
 
+**Breaking Changes**: If your PR introduces a breaking change, please add the `breaking change` label. This will trigger automation to help you document the change properly. See [Breaking Changes Automation](RELEASING.md#breaking-changes-automation) for more details.
+
 ## Building
 
 This project requires Java 21 to build and run tests. Newer JDK's may work, but this version is used in CI.

RELEASING.md

@@ -29,6 +29,7 @@ the second Monday of the month (roughly a few days after the monthly minor relea
 - Merge a pull request to `main` updating the `CHANGELOG.md`.
   - The heading for the unreleased entries should be `## Unreleased`.
   - Use `.github/scripts/draft-change-log-entries.sh` as a starting point for writing the change log.
+  - The script will automatically include a "Breaking Changes" section for PRs labeled with `breaking change`.
 - Run the [Prepare release branch workflow](https://github.com/open-telemetry/opentelemetry-java-instrumentation/actions/workflows/prepare-release-branch.yml).
   - Press the "Run workflow" button, and leave the default branch `main` selected.
   - Review and merge the two pull requests that it creates
@@ -72,6 +73,51 @@ and deadlocks.
     (note that if this is not a patch release then the change log on main may already be up-to-date,
     in which case no pull request will be created).
 
+## Breaking Changes Automation
+
+This project includes automation to help track and communicate breaking changes to users.
+
+### For Contributors
+
+When your PR introduces a breaking change:
+
+1. **Apply the Label**: Add the `breaking change` label to your PR
+2. **Respond to Automation**: A bot will comment with guidance on documenting the breaking change
+3. **Provide Migration Notes**: Add detailed migration notes to your PR description or as a comment, including:
+   - What is changing and why
+   - How users should update their code/configuration
+   - Code examples showing before/after usage
+   - Any alternative approaches if applicable
+
+### For Maintainers
+
+During PR review, ensure:
+- Migration notes are clear
+- The breaking change is properly categorized
+- The impact is well understood
+
+### Automation Details
+
+The breaking changes automation includes:
+
+- **PR Comment Bot** (`.github/workflows/breaking-change-pr-comment.yml`): Automatically comments on PRs with the `breaking change` label, providing guidance and a checklist for the author
+- **Changelog Integration** (`.github/scripts/extract-breaking-changes.sh`): Extracts PRs with breaking change labels and includes them in the changelog template
+- **Release Notes Enhancement** (`.github/workflows/release.yml`): Highlights breaking changes prominently in GitHub release notes
+
+Breaking changes are automatically:
+- Included in the "Breaking Changes" section of the changelog template generated by `draft-change-log-entries.sh`
+- Highlighted at the top of GitHub release notes with links to the original PRs
+- Linked to migration notes provided by contributors
+
+### Label Requirements
+
+- **Label Name**: `breaking change` (exact match, case sensitive)
+- **When to Use**:
+  - API changes that break backward compatibility
+  - Configuration changes that require user action
+  - Behavioral changes that might affect existing users
+  - Removal of deprecated features
+
 ## Credentials
 
 Same as the core repo, see [opentelemetry-java/RELEASING.md#credentials](https://github.com/open-telemetry/opentelemetry-java/blob/main/RELEASING.md#credentials).