diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ac34b577e7..717d0bd3fa2 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/dev-utils/update-4x-branch.sh b/dev-utils/update-4x-branch.sh new file mode 100755 index 00000000000..6166f6ba35b --- /dev/null +++ b/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 git@github.com: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'" +