chore: add a script for, and update the release process for updating …

…the 4.x docs branch (#3972)

CONTRIBUTING.md

@@ -202,19 +202,27 @@ A release involves the following published artifacts:
         ```
    If there are particular highlights for the release, then it can be helpful
    to point those out in the PR description.
+
 2. Get your PR reviewed, ensure PR checks pass, then merge.
+
 3. Working on the elastic repo now (not a fork), tag the merged commit with:
    `git tag vx.y.x && git push origin vx.y.z`.
    For example: `git tag v1.2.3 && git push origin v1.2.3`.
    (The GitHub Actions CI "release" workflow will handle all the release
    steps -- including the `npm publish`. See the appropriate run at:
    https://github.com/elastic/apm-agent-nodejs/actions/workflows/release.yml)
+
 4. If this is for the latest major (currently `4.x`), then the "4.x" branch
-   needs to be updated to the same state as the release tag on "main".
-   **Open a PR to rebase all commits from main on to the "4.x" branch,
-   get it approved, merge with the rebase strategy.**
-   (The periodic [docs CI job](https://elasticsearch-ci.elastic.co/view/Docs/job/elastic+docs+master+build/)
-   uses this branch to update the [published docs](https://www.elastic.co/guide/en/apm/agent/nodejs/current/release-notes-4.x.html).)
+   needs to be updated to the same state as the release tag on "main". Use
+   the [update-4x-branch.sh](./dev-utils/update-4x-branch.sh) script for this.
+
+    - Run `./dev-utils/update-4x-branch.sh` to create a working dir with the
+      needed changes.
+    - Follow its instructions to create a PR from this working dir.
+    - Ensure the "buildkite/docs-build-pr" workflow passes for this branch.
+    - "Squash and merge" the PR.
+    - The periodic docs CI will update the
+      [published docs](https://www.elastic.co/guide/en/apm/agent/nodejs/current/release-notes-4.x.html).
 
 If this is a new major release, then:
 

dev-utils/update-4x-branch.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+#
+# Create a PR to update the 4.x branch to match the state of "main" for the
+# just-tagged release. The 4.x branch needs to be updated for the current docs
+# build.
+#
+
+if [ "$TRACE" != "" ]; then
+    export PS4='${BASH_SOURCE}:${LINENO}: ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'
+    set -o xtrace
+fi
+set -o errexit
+set -o pipefail
+
+function fatal {
+    echo "$(basename $0): error: $*"
+    exit 1
+}
+
+TOP=$(cd $(dirname $0)/../ >/dev/null; pwd)
+WRKDIR=${TOP}/build/update-4x-branch
+
+echo "# Creating working git clone in: ${WRKDIR}/apm-agent-nodejs"
+rm -rf $WRKDIR
+mkdir -p $WRKDIR
+cd $WRKDIR
+git clone [email protected]:elastic/apm-agent-nodejs.git
+cd apm-agent-nodejs
+
+TARGTAG=$(git tag --points-at HEAD)
+if [[ ! ("$TARGTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]$) ]]; then
+    fatal "the tag on HEAD, '${TARGTAG}', does not look like a release tag"
+fi
+# echo "TARGTAG=$TARGTAG"
+
+readonly NUM_COMMITS_SANITY_GUARD=200
+LASTTAG=$(
+    git log --pretty=format:%h -$NUM_COMMITS_SANITY_GUARD | tail -n +2 | while read sha; do
+        possible=$(git tag --points-at $sha)
+        if [[ "$possible" =~ ^v[0-9]+\.[0-9]+\.[0-9]$ ]]; then
+            echo $possible
+            break
+        fi
+    done
+)
+if [[ -z "$LASTTAG" ]]; then
+    fatal "could not find previous release tag in last $NUM_COMMITS_SANITY_GUARD commits"
+fi
+# echo "LASTTAG=$LASTTAG"
+
+
+# Merging generally fails, IME. Let's attempt to cherry-pick each commit.
+# - That 'awk' command is to reverse the lines of commit shas.
+#   `tac` works on Linux, `tail -r` works on BSD/macOS.
+#   https://stackoverflow.com/a/744093/14444044
+echo
+echo "# Creating PR to update 4.x branch with commits from $LASTTAG to $TARGTAG."
+FEATBRANCH=update-4x-branch-$(date +%Y%m%d)
+git checkout 4.x
+git checkout -b "$FEATBRANCH"
+git log --pretty=format:"%h" $LASTTAG...$TARGTAG \
+    | awk '{a[i++]=$0} END {for (j=i-1; j>=0;) print a[j--] }' \
+    | while read sha; do
+        echo "$ git cherry-pick $sha"
+        git cherry-pick $sha
+    done
+
+echo
+echo "# You can create a PR now with:"
+echo "    cd $WRKDIR/apm-agent-nodejs"
+echo "    gh pr create --fill -w -B 4.x -t 'docs: update 4.x branch for $TARGTAG release'"
+