[release] improve release steps naming

.ci/release/update-major-branch.sh

@@ -68,4 +68,8 @@ git checkout -b "update-major-${v}"
 git push origin "update-major-${v}"
 
 echo -e "\n--- create PR to update major branch"
-gh pr create --title="post release v${v}: update major branch" --base "${major_branch}" --head "update-major-${v}" -b "post release v${v}"
+gh pr create \
+  --title="[release] release-step-4 ${v}" \
+  --base "${major_branch}" \
+  --head "update-major-${v}" \
+  -b "Step 4 of the release process for version ${v}: review & merge with merge commit WITHOUT SQUASH to prevent conflicts"

.github/workflows/README.md

@@ -36,11 +36,18 @@ Every time there is a merge to main or any branches the whole workflow will comp
 ### Release process
 
 To release a new version of apm-agent-java, you must use the two GitHub Workflows.
-Trigger the `Pre Release` workflow targeting the release version.
-After merging the PRs created by the first workflow, you can trigger the `Release` workflow targeting the release version.
-It runs then a Buildkite pipeline in charge of generating and publishing the artifacts,
-for further details please go to [the buildkite folder](../../.buildkite/README.md).
-Finally, merge the PRs created to bump version for the next iteration.
+
+- Trigger the `release-step-1` GH workflow
+  - parameters: version to release
+  - will open `release-step-2` PR
+- Review and merge the `release-step-2` PR to `main` (version bump to release + changelog update)
+- Trigger the `release-step-3` GH workflow
+  - parameters: version to release and the `main` branch (or merge commit/ref of `release-step-2` PR merge).
+  - will generate and publish release artifact through [buildkite](../../.buildkite/README.md).
+  - will open two PRs: `release-step-4` and `release-step-5`
+  - will wait on the `release-step-4` PR to be merged and published (documentation update)
+- Review and merge the `release-step-4` PR to the "major branch", which is currently `1.x`, the documentation effective build and publication can take a while.
+- Review and merge the `release-step-5` PR to `main` (version bump from release to next snapshot version)
 
 The tag release follows the naming convention: `v.<major>.<minor>.<patch>`, where `<major>`, `<minor>` and `<patch>`.
 

.github/workflows/pre-post-release.yml

@@ -18,6 +18,14 @@ on:
         description: 'Pre or post release phase'
         type: string # valid values are 'pre' or 'post'
         required: true
+      pr_title:
+        description: 'pull-request title'
+        type: string
+        required: true
+      pr_body:
+        description: : 'pull-request body'
+        type: string
+        required: true
 
 env:
   RELEASE_VERSION: ${{ inputs.version }}
@@ -91,8 +99,8 @@ jobs:
           git add --all
           git commit -m "${{ inputs.phase }} release: elastic-apm-agent ${{ env.RELEASE_VERSION_TAG }}"
           git push origin ${{ env.BRANCH_NAME }}
-  
+
       - name: Create the ${{ inputs.phase }} release PR
-        run: gh pr create --title="${{ inputs.phase }} release ${{ env.RELEASE_VERSION_TAG }}" --base main --head ${{ env.BRANCH_NAME }} -b "${{ inputs.phase }} release ${{ env.RELEASE_VERSION_TAG }}"
+        run: gh pr create --title="${{ inputs.pr_title }}" --base main --head ${{ env.BRANCH_NAME }} -b "${{ inputs.pr_body }}"
         env:
           GH_TOKEN: ${{ env.GITHUB_TOKEN }}

.github/workflows/pre-release.yml → .github/workflows/release-step-1.yml

@@ -1,6 +1,6 @@
 ---
 
-name: Pre release
+name: 'release-step-1'
 
 on:
   workflow_dispatch:
@@ -29,4 +29,6 @@ jobs:
       ref: ${{ inputs.ref }}
       version: ${{ inputs.version }}
       phase: 'pre'
+      pr_title: "[release] release-step-2 ${{ inputs.version }}"
+      pr_body: "Step 2 of the release process for version ${{ inputs.version }}: review & merge, then execute 'release-step-3' GH workflow"
     secrets: inherit

.github/workflows/release.yml → .github/workflows/release-step-3.yml

@@ -1,6 +1,6 @@
 ---
 # Releases the agent
-name: release
+name: 'release-step-3'
 
 on:
   workflow_dispatch:
@@ -10,7 +10,7 @@ on:
         required: true
         default: "main"
       version:
-        description: 'The version to release (e.g. 1.2.3). This workflow will automatically perform the required version bumps'
+        description: 'The version to release (e.g. 1.2.3). This workflow will automatically perform the required post-release version bumps'
         required: true
       skip_preparation:
         description: |
@@ -55,7 +55,7 @@ jobs:
         uses: ./.github/workflows/validate-tag
         with:
           tag: ${{ env.RELEASE_VERSION_TAG }}
-      - name: Validate tag match current version
+      - name: Validate tag match current maven project version
         run: |
           if [ "$(./mvnw -q help:evaluate -Dexpression=project.version -DforceStdout)" != "${{ env.RELEASE_VERSION }}" ]; then
             echo "Tag should match pom.xml project.version"
@@ -212,6 +212,8 @@ jobs:
       ref: ${{ inputs.ref }}
       version: ${{ inputs.version }}
       phase: 'post'
+      pr_title: "[release] release-step-5 ${{ inputs.version }}"
+      pr_body: "Step 5 of the release process for version ${{ inputs.version }}: review & merge"
     secrets: inherit
 
   update-major-branch: