feat: Improve milestone automation (#7553)

Rewrite milestone update on tag
Add workflow testing
Update README

Author: PerfectSlayer

.github/workflows/README.md

@@ -1,6 +1,6 @@
 # GitHub Actions Documentation
 
-This lists and describes the repository GitHub actions.
+This lists and describes the repository GitHub actions, how to maintain and test them.
 
 ## Release Management
 
@@ -18,15 +18,16 @@ _Trigger:_ When a release is published.
 
 _Action:_ Append the new release to the Cloud Foundry repository.
 
-_Recovery:_ Manually edit and push the `index.yml` file from [the cloudfoundry branch](https://github.com/DataDog/dd-trace-java/tree/cloudfoundry).
+_Recovery:_ Manually edit and push the `index.yml` file from [the cloudfoundry branch](https://github.com/DataDog/dd-trace-java/tree/cloudfoundry).
 
 ### create-next-milestone [🔗](create-next-milestone.yaml)
 
 _Trigger:_ When closing a milestone.
 
 _Action:_ Create a new milestone by incrementing minor version.
 
-_Comment:_ Already done when closing a tag. To delete?
+_Comment:_ Disabled as also covered by increment-milestone-on-tag.
+This will be removed after some testing.  
 
 ### draft-release-notes-on-tag [🔗](draft-release-notes-on-tag.yaml)
 
@@ -40,18 +41,17 @@ _Actions:_
 
 _Recovery:_ Manually trigger the action again on the relevant tag.
 
-### increment-milestones-on-tag [🔗](increment-milestones-on-tag.yaml)
+### increment-milestone-on-tag [🔗](increment-milestone-on-tag.yaml)
 
-_Trigger:_ When creating a tag. Release Candidate tags containing "-RC" or "-rc" will skip this.
+_Trigger:_ When creating a minor or major version tag.
 
 _Actions:_
 * Close the milestone related to the tag,
 * Create a new milestone by incrementing minor version.
 
-_Recovery:_ Manually close the related milestone and create a new one.
+_Recovery:_ Manually [close the related milestone and create a new one](https://github.com/DataDog/dd-trace-java/milestones).
 
-_Notes:_ This actions will handle _minor_ releases only.
-As there is no milestone for _patch_ releases, it won't close and create _patch_ releated milestone.
+_Notes:_ This action will not apply to release candidate versions using `-RC` tags.
 
 ### update-download-releases [🔗](update-download-releases.yaml)
 
@@ -117,3 +117,12 @@ Run the following script to get the list of actions to declare according the sta
 ```bash
 find .github/workflows -name "*.yaml" -exec  awk '/uses:/{print $2 ","}' {} \; | grep -vE '^(actions|github)/' | sort | uniq
 ```
+
+## Testing
+
+Workflows can be locally tested using the [`act` CLI](https://github.com/nektos/act/).
+The [.github/workflows/tests/](./tests) folder contains test scripts and event payloads to locally trigger workflows.
+
+> [!WARNING]
+> Locally running workflows will still query GitHub backend and will update the GitHub project accordingly.
+> Pay extra attention to the workflow jobs you trigger to not create development disruption.

.github/workflows/increment-milestone-on-tag.yaml

@@ -0,0 +1,64 @@
+name: Increment milestones on tag
+on:
+  create
+permissions:
+  issues: write # Required to update milestones
+
+jobs:
+  increment_milestone:
+    if: github.event.ref_type == 'tag' && contains(github.event.ref,'-RC') == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Close current milestone
+        id: close-milestone
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # 7.0.1
+        with:
+          script: |
+            // Get the milestone title ("X.Y.Z") from tag name ("vX.Y.Z")
+            const match = '${{github.event.ref}}'.match(/v(\d+\.\d+\.\d+)/i)
+            if (!match) {
+              core.setFailed('Failed to parse tag name into milestone title: ${{github.event.ref}}')
+              return
+            }
+            const milestoneTitle = match[1]
+            // Look for the milestone from its title
+            const response = await github.rest.issues.listMilestones({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open'
+            })
+            if (!response.data || response.data.length == 0) {
+              core.setFailed(`Failed to list milestones: ${response.status}`)
+              return
+            }
+            const milestone = response.data.find(milestone => milestone.title == milestoneTitle)
+            if (!milestone) {
+              core.setFailed(`Failed to find milestone: ${milestoneTitle}`)
+              return
+            }
+            // Close the milestone
+            await github.rest.issues.updateMilestone({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'closed',
+              milestone_number: milestone.number
+            }).catch(error => {
+              core.setFailed(`Failed to close milestone: ${error}`)
+            })
+            // Compute the next milestone version
+            const versionNumbers = milestoneTitle.split('.').map(Number)
+            if (versionNumbers[2] != 0) {
+              core.info('Closing a patch version milestone. Not opening a new one.')
+              return
+            }
+            versionNumbers[1]++
+            const nextMilestoneTitle = versionNumbers.join('.')
+            core.info(`Creating next version milestone: ${nextMilestoneTitle}`)
+            // Create the next milestone
+            await github.issues.createMilestone({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: nextMilestoneTitle
+            }).catch(error => {
+              core.setFailed(`Failed to create milestone ${nextMilestoneTitle}: ${error}`)
+            })

.github/workflows/increment-milestones-on-tag.yaml

@@ -0,0 +1,9 @@
+{
+    "pull_request": {
+        "number": 7549,
+        "base": {
+            "ref": "master"
+        },
+        "merged": true
+    }
+}

.github/workflows/tests/add-milestone-to-pull-requests/payload.json

@@ -0,0 +1,3 @@
+#!/bin/bash
+source $(dirname "$0")/../env.sh
+act pull_request --workflows .github/workflows/add-milestone-to-pull-requests.yaml --eventpath .github/workflows/tests/add-milestone-to-pull-requests/payload.json $COMMON_ACT_ARGS

.github/workflows/tests/add-milestone-to-pull-requests/test.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+# Move to project root directory
+FILE_PATH=$(dirname "$0")
+cd $FILE_PATH/../../../../
+
+export COMMON_ACT_ARGS="--container-architecture linux/amd64 --secret GITHUB_TOKEN="$(gh auth token)" --verbose"

.github/workflows/tests/env.sh

@@ -0,0 +1,4 @@
+{
+    "ref_type": "tag",
+    "ref": "v1.40.0"
+}

.github/workflows/tests/increment-milestone-on-tag/payload.json

@@ -0,0 +1,3 @@
+#!/bin/bash
+source $(dirname "$0")/../env.sh
+act create --workflows .github/workflows/increment-milestone-on-tag.yaml --eventpath .github/workflows/tests/increment-milestone-on-tag/payload.json $COMMON_ACT_ARGS