Automation for tracking breaking changes

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

@@ -15,31 +15,29 @@ if [[ $minor == 0 ]]; then
   prior_minor=$(sed -n "s/^## Version $prior_major\.\([0-9]\+\)\..*/\1/p" CHANGELOG.md | head -1)
   if [[ -z $prior_minor ]]; then
     # assuming this is the first release
-    range=
+    range=HEAD
   else
     range="v$prior_major.$prior_minor.0..HEAD"
   fi
 else
   range="v$major.$((minor - 1)).0..HEAD"
 fi
 
-echo "## Unreleased"
-echo
-echo "### Migration notes"
+echo "# Changelog"
 echo
+echo "## Unreleased"
 echo
+
+"$(dirname "$0")/extract-labeled-prs.sh" "$range"
+
 echo "### 🌟 New javaagent instrumentation"
 echo
-echo
 echo "### 🌟 New library instrumentation"
 echo
-echo
 echo "### 📈 Enhancements"
 echo
-echo
 echo "### 🛠️ Bug fixes"
 echo
-echo
 echo "### 🧰 Tooling"
 echo
 
@@ -48,4 +46,5 @@ git log --reverse \
         --author='^(?!renovate\[bot\] )' \
         --pretty=format:"- %s" \
         "$range" \
-  | sed -E 's,\(#([0-9]+)\)$,\n  ([#\1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/\1)),'
+  | sed -E 's, *\(#([0-9]+)\)$,\n  ([#\1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/\1)),'
+echo

.github/scripts/extract-labeled-prs.sh

@@ -0,0 +1,78 @@
+#!/bin/bash -e
+
+# This script extracts PRs with "breaking change" and "deprecation" labels for the given version range
+# Usage: extract-labeled-prs.sh [git-range]
+# If no range is provided, it uses HEAD
+
+range="${1:-HEAD}"
+
+# Get the date range for filtering
+if [[ "$range" == "HEAD" ]]; then
+  # Get all commits from HEAD
+  oldest_commit=$(git log --reverse --pretty=format:"%H" HEAD | head -1)
+  since_date=$(git show -s --format=%ci "$oldest_commit" | cut -d' ' -f1)
+else
+  # Get commits in the specified range
+  if [[ $range =~ ^(.+)\.\.(.+)$ ]]; then
+    from_ref="${BASH_REMATCH[1]}"
+    oldest_commit=$(git rev-parse "$from_ref")
+    since_date=$(git show -s --format=%ci "$oldest_commit" | cut -d' ' -f1)
+  else
+    echo "[ERROR] Invalid range format: $range" >&2
+    exit 1
+  fi
+fi
+
+# Initialize tracking variables
+breaking_changes=""
+deprecations=""
+breaking_changes_found=false
+deprecations_found=false
+
+# Get PRs with "breaking change" label using GitHub search
+breaking_prs=$(gh pr list \
+  --repo open-telemetry/opentelemetry-java-instrumentation \
+  --label "breaking change" \
+  --state merged \
+  --search "merged:>=$since_date" \
+  --json number,title \
+  --jq '.[] | "\(.number)|\(.title)"' 2>/dev/null || echo "")
+
+if [[ -n "$breaking_prs" ]]; then
+  breaking_changes_found=true
+  while IFS='|' read -r pr_number pr_title; do
+    breaking_changes+="- $pr_title"$'\n'"  ([#$pr_number](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/$pr_number))"$'\n'
+  done <<< "$breaking_prs"
+fi
+
+# Get PRs with "deprecation" label using GitHub search
+deprecation_prs=$(gh pr list \
+  --repo open-telemetry/opentelemetry-java-instrumentation \
+  --label "deprecation" \
+  --state merged \
+  --search "merged:>=$since_date" \
+  --json number,title \
+  --jq '.[] | "\(.number)|\(.title)"' 2>/dev/null || echo "")
+
+if [[ -n "$deprecation_prs" ]]; then
+  deprecations_found=true
+  while IFS='|' read -r pr_number pr_title; do
+    deprecations+="- $pr_title"$'\n'"  ([#$pr_number](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/$pr_number))"$'\n'
+  done <<< "$deprecation_prs"
+fi
+
+# Output breaking changes section
+if [[ "$breaking_changes_found" == "true" ]]; then
+  echo "### ⚠️ Breaking Changes"
+  echo
+  echo -n "$breaking_changes"
+  echo
+fi
+
+# Output deprecations section
+if [[ "$deprecations_found" == "true" ]]; then
+  echo "### 🚫 Deprecations"
+  echo
+  echo -n "$deprecations"
+  echo
+fi

.github/workflows/pr-automation-comments.yml

@@ -0,0 +1,112 @@
+name: PR Automation Comments
+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",
+                "- [ ] 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
+              });
+            }
+
+  comment-on-deprecation:
+    if: contains(github.event.label.name, 'deprecation')
+    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 deprecation
+            const botComment = comments.find(comment => 
+              comment.user.login === 'github-actions[bot]' && 
+              comment.body.includes('📋 Deprecation Notice')
+            );
+
+            if (!botComment) {
+              const commentBody = [
+                "## 📋 Deprecation Notice",
+                "",
+                "This PR has been labeled as a **deprecation**. Please ensure you provide the following information:",
+                "",
+                "### 📝 Deprecation Details Required",
+                "Please add details to help users understand:",
+                "- What is being deprecated and why",
+                "- What should be used instead (if applicable)",
+                "- Timeline for removal (if known)",
+                "- Any migration guidance",
+                "",
+                "### 📋 Checklist",
+                "- [ ] Deprecation details added to the PR description",
+                "- [ ] Deprecation is documented in the changelog entry for the next release",
+                "- [ ] Consider adding deprecation warnings in code/documentation",
+                "",
+                "Your deprecation notes will be included in the release notes to help users prepare for future changes.",
+                "",
+                "---",
+                "*This comment was automatically generated because the `deprecation` 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/pr-label-automation.yml

@@ -0,0 +1,73 @@
+name: PR Label Automation
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  auto-label:
+    # Only run on pull request comments
+    if: github.event.issue.pull_request != null
+    runs-on: ubuntu-latest
+    steps:
+      - name: Add breaking change label
+        if: github.event.comment.body == '/breaking-change'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            // Add the breaking change label
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['breaking change']
+            });
+
+            // React to the comment to show it was processed
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: '+1'
+            });
+
+            // Add a reply comment to confirm the action
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: '✅ Added `breaking change` label to this PR.'
+            });
+
+      - name: Add deprecation label
+        if: github.event.comment.body == '/deprecation'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            // Add the deprecation label
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['deprecation']
+            });
+
+            // React to the comment to show it was processed
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: '+1'
+            });
+
+            // Add a reply comment to confirm the action
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: '✅ Added `deprecation` label to this PR.'
+            });

CONTRIBUTING.md

@@ -6,6 +6,37 @@ 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
+
+When your PR introduces a breaking change:
+
+* Add the `breaking change` label to your PR
+  - If you can't add labels directly, post a comment containing only `/breaking-change` and the label will be added automatically
+* Provide migration notes in the PR description:
+  - What is changing and why
+  - How users should update their code/configuration
+  - Code examples showing before/after usage (if applicable)
+
+**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
+
+## Deprecations
+
+When your PR deprecates functionality:
+
+* Add the `deprecation` label to your PR
+  - If you can't add labels directly, post a comment containing only `/deprecation` and the label will be added automatically
+* Provide deprecation details in the PR description:
+  - What is being deprecated and why
+  - What should be used instead (if applicable)
+  - Timeline for removal (if known)
+  - Any migration guidance
+
 ## 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,8 @@ 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`.
+  - The script will automatically include a "Deprecations" section for PRs labeled with `deprecation`.
 - 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