Skip to content

Commit 866c6c5

Browse files
jaydelucajaydeluca
committed
add deprecation flow
1 parent f3cb98a commit 866c6c5

File tree

7 files changed

+280
-56
lines changed

7 files changed

+280
-56
lines changed

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,14 @@ echo "### Migration notes"
2929
echo
3030
echo
3131

32-
# Add breaking changes section
32+
# Add breaking changes and deprecations sections
3333
if [[ -z $range ]]; then
34-
breaking_range="HEAD"
34+
labeled_range="HEAD"
3535
else
36-
breaking_range="$range"
36+
labeled_range="$range"
3737
fi
3838

39-
"$(dirname "$0")/extract-breaking-changes.sh" "$breaking_range"
39+
"$(dirname "$0")/extract-labeled-prs.sh" "$labeled_range"
4040
echo
4141

4242
echo "### 🌟 New javaagent instrumentation"

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

Lines changed: 0 additions & 46 deletions
This file was deleted.

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

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
#!/bin/bash -e
2+
3+
# This script extracts PRs with "breaking change" and "deprecation" labels for the given version range
4+
# Usage: extract-labeled-prs.sh [git-range]
5+
# If no range is provided, it uses HEAD
6+
7+
range="${1:-HEAD}"
8+
9+
if [[ "$range" == "HEAD" ]]; then
10+
# Get all commits from HEAD
11+
commits=$(git log --reverse --pretty=format:"%H %s" HEAD)
12+
else
13+
# Get commits in the specified range
14+
commits=$(git log --reverse --pretty=format:"%H %s" "$range")
15+
fi
16+
17+
# Initialize tracking variables
18+
breaking_changes=""
19+
deprecations=""
20+
breaking_changes_found=false
21+
deprecations_found=false
22+
23+
# Process each commit to find PRs with specified labels
24+
while IFS= read -r line; do
25+
if [[ -z "$line" ]]; then
26+
continue
27+
fi
28+
29+
# Extract PR number from commit message
30+
if [[ $line =~ \(#([0-9]+)\)$ ]]; then
31+
pr_number="${BASH_REMATCH[1]}"
32+
commit_subject=$(echo "$line" | cut -d' ' -f2- | sed 's/ (#[0-9]*)$//')
33+
34+
# Get PR labels using GitHub CLI
35+
if pr_labels=$(gh pr view "$pr_number" --json labels --jq '.labels[].name' 2>/dev/null); then
36+
# Check for breaking change label
37+
if echo "$pr_labels" | grep -q "^breaking change$"; then
38+
breaking_changes_found=true
39+
breaking_changes+="- $commit_subject"$'\n'" ([#$pr_number](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/$pr_number))"$'\n'$'\n'
40+
fi
41+
42+
# Check for deprecation label
43+
if echo "$pr_labels" | grep -q "^deprecation$"; then
44+
deprecations_found=true
45+
deprecations+="- $commit_subject"$'\n'" ([#$pr_number](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/$pr_number))"$'\n'$'\n'
46+
fi
47+
fi
48+
fi
49+
done <<< "$commits"
50+
51+
# Output breaking changes section
52+
if [[ "$breaking_changes_found" == "true" ]]; then
53+
echo "### ⚠️ Breaking Changes"
54+
echo
55+
echo -n "$breaking_changes"
56+
fi
57+
58+
# Output deprecations section
59+
if [[ "$deprecations_found" == "true" ]]; then
60+
echo "### 🚫 Deprecations"
61+
echo
62+
echo -n "$deprecations"
63+
fi
64+
65+
# Output "no changes" messages if needed
66+
if [[ "$breaking_changes_found" == "false" ]]; then
67+
echo "### ⚠️ Breaking Changes"
68+
echo
69+
echo "*No breaking changes in this release.*"
70+
echo
71+
fi
72+
73+
if [[ "$deprecations_found" == "false" ]]; then
74+
echo "### 🚫 Deprecations"
75+
echo
76+
echo "*No deprecations in this release.*"
77+
echo
78+
fi

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ if [[ ! -f "$changelog_section" ]]; then
1616
exit 1
1717
fi
1818

19-
# Generate all output and redirect to file at once
2019
{
2120
# Add breaking changes section if it exists
2221
if grep -q "### ⚠️ Breaking Changes" "$changelog_section"; then
@@ -35,6 +34,23 @@ EOF
3534
echo -e "\n---\n"
3635
fi
3736

37+
# Add deprecations section if it exists
38+
if grep -q "### 🚫 Deprecations" "$changelog_section"; then
39+
cat << 'EOF'
40+
41+
## 🚫 Deprecations
42+
43+
This release includes deprecations. Please review the changes below and plan for future updates:
44+
45+
EOF
46+
47+
# Extract deprecations section, format for release notes
48+
sed -n '/### 🚫 Deprecations/,/^### /p' "$changelog_section" | sed '$d' | \
49+
perl -0pe 's/(?<!\n)\n *(?!\n)(?![-*] )(?![1-9]+\. )/ /g'
50+
51+
echo -e "\n---\n"
52+
fi
53+
3854
# the complex perl regex is needed because markdown docs render newlines as soft wraps
3955
# while release notes render them as line breaks
4056
perl -0pe 's/(?<!\n)\n *(?!\n)(?![-*] )(?![1-9]+\. )/ /g' "$changelog_section"

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

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Breaking Change PR Comment
1+
name: PR Automation Comments
22
on:
33
pull_request:
44
types: [labeled]
@@ -58,3 +58,55 @@ jobs:
5858
body: commentBody
5959
});
6060
}
61+
62+
comment-on-deprecation:
63+
if: contains(github.event.label.name, 'deprecation')
64+
runs-on: ubuntu-latest
65+
steps:
66+
- name: Comment on PR
67+
uses: actions/github-script@v7
68+
with:
69+
script: |
70+
const { data: comments } = await github.rest.issues.listComments({
71+
owner: context.repo.owner,
72+
repo: context.repo.repo,
73+
issue_number: context.issue.number,
74+
});
75+
76+
// Check if we've already commented about deprecation
77+
const botComment = comments.find(comment =>
78+
comment.user.login === 'github-actions[bot]' &&
79+
comment.body.includes('🚫 Deprecation Notice')
80+
);
81+
82+
if (!botComment) {
83+
const commentBody = [
84+
"## 🚫 Deprecation Notice",
85+
"",
86+
"This PR has been labeled as a **deprecation**. Please ensure you provide the following information:",
87+
"",
88+
"### 📝 Deprecation Details Required",
89+
"Please add details to help users understand:",
90+
"- What is being deprecated and why",
91+
"- What should be used instead (if applicable)",
92+
"- Timeline for removal (if known)",
93+
"- Any migration guidance",
94+
"",
95+
"### 📋 Checklist",
96+
"- [ ] Deprecation details added to the PR description or as a comment",
97+
"- [ ] Deprecation is documented in the changelog entry for the next release",
98+
"- [ ] Consider adding deprecation warnings in code/documentation",
99+
"",
100+
"Your deprecation notes will be included in the release notes to help users prepare for future changes.",
101+
"",
102+
"---",
103+
"*This comment was automatically generated because the `deprecation` label was applied to this PR.*"
104+
].join("\n");
105+
106+
await github.rest.issues.createComment({
107+
owner: context.repo.owner,
108+
repo: context.repo.repo,
109+
issue_number: context.issue.number,
110+
body: commentBody
111+
});
112+
}

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
name: PR Automation Comments
2+
on:
3+
pull_request:
4+
types: [labeled]
5+
6+
permissions:
7+
pull-requests: write
8+
9+
jobs:
10+
comment-on-breaking-change:
11+
if: contains(github.event.label.name, 'breaking change')
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Comment on PR
15+
uses: actions/github-script@v7
16+
with:
17+
script: |
18+
const { data: comments } = await github.rest.issues.listComments({
19+
owner: context.repo.owner,
20+
repo: context.repo.repo,
21+
issue_number: context.issue.number,
22+
});
23+
24+
// Check if we've already commented about breaking changes
25+
const botComment = comments.find(comment =>
26+
comment.user.login === 'github-actions[bot]' &&
27+
comment.body.includes('⚠️ Breaking Change Documentation Required')
28+
);
29+
30+
if (!botComment) {
31+
const commentBody = [
32+
"## ⚠️ Breaking Change Documentation Required",
33+
"",
34+
"This PR has been labeled as a **breaking change**. Please ensure you provide the following information:",
35+
"",
36+
"### Migration Notes Required",
37+
"Please add detailed migration notes to help users understand:",
38+
"- What is changing and why",
39+
"- How to update their code/configuration",
40+
"- Any alternative approaches if applicable",
41+
"- Code examples showing before/after usage",
42+
"",
43+
"### Checklist",
44+
"- [ ] Migration notes added to the PR description or as a comment",
45+
"- [ ] Breaking change is documented in the changelog entry for the next release",
46+
"- [ ] Consider if this change requires a major version bump",
47+
"",
48+
"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.",
49+
"",
50+
"---",
51+
"*This comment was automatically generated because the `breaking change` label was applied to this PR.*"
52+
].join("\n");
53+
54+
await github.rest.issues.createComment({
55+
owner: context.repo.owner,
56+
repo: context.repo.repo,
57+
issue_number: context.issue.number,
58+
body: commentBody
59+
});
60+
}
61+
62+
comment-on-deprecation:
63+
if: contains(github.event.label.name, 'deprecation')
64+
runs-on: ubuntu-latest
65+
steps:
66+
- name: Comment on PR
67+
uses: actions/github-script@v7
68+
with:
69+
script: |
70+
const { data: comments } = await github.rest.issues.listComments({
71+
owner: context.repo.owner,
72+
repo: context.repo.repo,
73+
issue_number: context.issue.number,
74+
});
75+
76+
// Check if we've already commented about deprecation
77+
const botComment = comments.find(comment =>
78+
comment.user.login === 'github-actions[bot]' &&
79+
comment.body.includes('📋 Deprecation Notice')
80+
);
81+
82+
if (!botComment) {
83+
const commentBody = [
84+
"## 📋 Deprecation Notice",
85+
"",
86+
"This PR has been labeled as a **deprecation**. Please ensure you provide the following information:",
87+
"",
88+
"### 📝 Deprecation Details Required",
89+
"Please add details to help users understand:",
90+
"- What is being deprecated and why",
91+
"- What should be used instead (if applicable)",
92+
"- Timeline for removal (if known)",
93+
"- Any migration guidance",
94+
"",
95+
"### 📋 Checklist",
96+
"- [ ] Deprecation details added to the PR description or as a comment",
97+
"- [ ] Deprecation is documented in the changelog entry for the next release",
98+
"- [ ] Consider adding deprecation warnings in code/documentation",
99+
"",
100+
"Your deprecation notes will be included in the release notes to help users prepare for future changes.",
101+
"",
102+
"---",
103+
"*This comment was automatically generated because the `deprecation` label was applied to this PR.*"
104+
].join("\n");
105+
106+
await github.rest.issues.createComment({
107+
owner: context.repo.owner,
108+
repo: context.repo.repo,
109+
issue_number: context.issue.number,
110+
body: commentBody
111+
});
112+
}

‎RELEASING.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ the second Monday of the month (roughly a few days after the monthly minor relea
3030
- The heading for the unreleased entries should be `## Unreleased`.
3131
- Use `.github/scripts/draft-change-log-entries.sh` as a starting point for writing the change log.
3232
- The script will automatically include a "Breaking Changes" section for PRs labeled with `breaking change`.
33+
- The script will automatically include a "Deprecations" section for PRs labeled with `deprecation`.
3334
- Run the [Prepare release branch workflow](https://github.com/open-telemetry/opentelemetry-java-instrumentation/actions/workflows/prepare-release-branch.yml).
3435
- Press the "Run workflow" button, and leave the default branch `main` selected.
3536
- Review and merge the two pull requests that it creates
@@ -73,21 +74,32 @@ and deadlocks.
7374
(note that if this is not a patch release then the change log on main may already be up-to-date,
7475
in which case no pull request will be created).
7576

76-
## Breaking Changes Automation
77+
## Breaking Changes and Deprecations Automation
7778

78-
This project includes automation to help track and communicate breaking changes to users.
79+
This project includes automation to help track and communicate breaking changes and deprecations to users.
7980

8081
### For Contributors
8182

83+
#### Breaking Changes
8284
When your PR introduces a breaking change:
8385

8486
1. **Apply the Label**: Add the `breaking change` label to your PR
8587
2. **Respond to Automation**: A bot will comment with guidance on documenting the breaking change
8688
3. **Provide Migration Notes**: Add detailed migration notes to your PR description or as a comment, including:
8789
- What is changing and why
8890
- How users should update their code/configuration
89-
- Code examples showing before/after usage
90-
- Any alternative approaches if applicable
91+
- Code examples showing before/after usage (if applicable)
92+
93+
#### Deprecations
94+
When your PR deprecates functionality:
95+
96+
1. **Apply the Label**: Add the `deprecation` label to your PR
97+
2. **Respond to Automation**: A bot will comment with guidance on documenting the deprecation
98+
3. **Provide Deprecation Details**: Add details to your PR description or as a comment, including:
99+
- What is being deprecated and why
100+
- What should be used instead (if applicable)
101+
- Timeline for removal (if known)
102+
- Any migration guidance
91103

92104
### For Maintainers
93105

0 commit comments

Comments
 (0)