From fba08856ee927f1000db1339e03efe66887f3e63 Mon Sep 17 00:00:00 2001 From: Trent Mick Date: Mon, 14 Aug 2023 11:30:13 -0700 Subject: [PATCH] docs: document active branches, prep the release process for having a maintenance branch (#3573) - chore: simplify and doc push-docker.sh dev script - some cleanup of CONTRIBUTING content - docs: better document the release process, prepping for a coming 4.x new major Refs: https://github.com/elastic/apm-agent-nodejs/issues/2668 --- CONTRIBUTING.md | 92 ++++++++++++++++++++++++---------------- README.md | 8 ++++ dev-utils/push-docker.sh | 52 +++++++++-------------- 3 files changed, 83 insertions(+), 69 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d58e13dd40..31c2941a0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,7 @@ Once your changes are ready to submit for review: choose a title which sums up the changes that you have made, and in the body provide more details about what your changes do. Also mention the number of the issue where discussion has taken place, - e.g. "Closes #123". + e.g. "Closes: #123". 5. Be patient @@ -116,32 +116,30 @@ Of these guidelines, #1 and #3 are the most important. A succinct description and a body that answers "what" and "why" will best help future maintainers of the software. +An example: -### Testing - -For information about how to run the test suite, -see [TESTING.md](TESTING.md). +``` +feat: initial ESM support +This adds initial and ECMAScript Module (ESM) support, i.e. `import ...`, +via the `--experimental-loader=elastic-apm-node/loader.mjs` node option. +This instruments a subset of modules -- more will follow in subsequent changes. -### Backporting +Other changes: +- Fixes a fastify instrumentation issue where the exported `fastify.errorCodes` + was broken by instrumentation (both CJS and ESM). +- Adds a `runTestFixtures` utility that should be useful for running out of + process instrumentation/agent tests. -If a PR is marked with a `backport:*` label, -it should be backported to the branch specified by the label after it has been merged. +Closes: #1952 +Refs: #2343 +``` -To backport a commit, -run the following command and follow the instructions in the terminal: -``` -npm run backport -``` +### Testing -### Workflow +For information about how to run the test suite, see [TESTING.md](TESTING.md). -All feature development and most bug fixes hit the main branch first. -Pull requests should be reviewed by someone with commit access. -Once approved, the author of the pull request, -or reviewer if the author does not have commit access, -should "Squash and merge". ### Adding support for new modules @@ -167,13 +165,32 @@ The following is an overview of what's required in order to add support to the a ## Releasing -If you have access to make releases, the process is as follows: +At a given time there may be one or more active git branches: +- the `main` branch is used for releases of the current major, and +- there may be zero or more maintenance branches for past major versions. + +See the [Active release branches](https://github.com/elastic/apm-agent-nodejs#active-release-branches) +section in the main README. + +A release involves the following published artifacts: -### Current major +- **npm**: A new release to . + If the release is for the current major version, the "latest" npm dist-tag is applied. + Maintenance releases use a "latest-" npm dist-tag, e.g. "latest-2". +- **docker image**: A new "docker.elastic.co/observability/apm-agent-nodejs:" + Docker image is published. If the release is for the current major, then the + "latest" Docker tag is also applied. +- **AWS Lambda layers**: A new AWS Lambda layer for the APM agent is published + in each AWS region. For example, "arn:aws:lambda:us-east-1:267093732750:layer:elastic-apm-node-ver-3-49-1:1" + for the 3.49.1 version in the us-east-1 AWS region. +- **GitHub release**: A new release entry is added to . + If the release is for the current major version, the "latest" tag is applied. -1. Be sure you have checked out the `main` branch and have pulled latest - changes. -2. Make a PR titled "x.y.z" (the new version) which updates: + +### Release process + +1. Make a PR titled "x.y.z" (the new version) targetting the appropriate active + branch, which updates: - the version in `package.json`, - the version in `package-lock.json` (by running `npm install`), - all cases of "REPLACEME" in docs and comments, @@ -183,22 +200,25 @@ If you have access to make releases, the process is as follows: [[release-notes-x.y.z]] ==== x.y.z - YYYY/MM/DD ``` -3. Ensure PR checks pass, then merge to main. -4. Working on the elastic repo now (not a fork), tag the merged-to-main 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`. + 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) -5. Reset the latest major branch (currently `3.x`) to point to the current - main, e.g. `git branch -f 3.x main && git push origin 3.x`. +4. If this is the for the latest major (currently `3.x`), then reset the latest + major branch to point to the current main, e.g.: + `git branch -f 3.x main && git push origin 3.x` (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-3.x.html).) -6. For major releases, [create an issue](https://github.com/elastic/website-requests/issues/new) to request an update of the [EOL table](https://www.elastic.co/support/eol). - -### Past major -This is not currently supported. Until [this issue](#2668) is resolved one -**must not** push a "vX.Y.Z" version tag to the repository on GitHub that is -for a version other than the current major. +If this is a new major release, then: +- [Create an issue](https://github.com/elastic/website-requests/issues/new) to request an update of the [EOL table](https://www.elastic.co/support/eol). +- Update the "Active release branches" section of the main README. +- Update the "release.yml" for the new "N.x" *maintenance* branch as follows: + - The `npm publish ...` call must include a `--tag=latest-` option. + - The `gh release create ...` call must include a `--latest=false` option. diff --git a/README.md b/README.md index 007cf11e21..f2456d6681 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,14 @@ npm install elastic-apm-node --save - [Upgrading](https://www.elastic.co/guide/en/apm/agent/nodejs/current/upgrading.html) - [Troubleshooting](https://www.elastic.co/guide/en/apm/agent/nodejs/current/troubleshooting.html) + +## Active release branches + +Currently the only active release branch is the +["main" branch](https://github.com/elastic/apm-agent-nodejs/tree/main), which is +used for 3.x versions. + + ## Contributing Contributions are welcome, diff --git a/dev-utils/push-docker.sh b/dev-utils/push-docker.sh index 0123dc8e1d..8363c11be6 100755 --- a/dev-utils/push-docker.sh +++ b/dev-utils/push-docker.sh @@ -1,46 +1,32 @@ #!/usr/bin/env bash -set -euo pipefail - -# This script is present on workers but may not be present in a development -# environment. -if [ ${WORKSPACE+x} ] # We are on a CI worker -then - source /usr/local/bin/bash_standard_lib.sh -fi +# Publish (push) the given locally built Docker image. If 'v${IMAGE_TAG}' +# matches the latest git tag, then the image is also published with the 'latest' +# tag. +# +# This assumes that 'docker login REGISTRY' has already been done. +# +# Usage: +# ./dev-utils/push-docker.sh REGISTRY IMAGE_NAME IMAGE_TAG +# Example: +# ./dev-utils/push-docker.sh docker.elastic.co observability/apm-agent-nodejs 3.49.1 -readonly RETRIES=3 +set -euo pipefail readonly DOCKER_REGISTRY_URL="$1" - readonly DOCKER_IMAGE_NAME="$2" - readonly DOCKER_TAG="$3" - readonly DOCKER_PUSH_IMAGE="$DOCKER_REGISTRY_URL/$DOCKER_IMAGE_NAME:$DOCKER_TAG" - readonly DOCKER_PUSH_IMAGE_LATEST="$DOCKER_REGISTRY_URL/$DOCKER_IMAGE_NAME:latest" -echo "INFO: Pushing image $DOCKER_PUSH_IMAGE to $DOCKER_REGISTRY_URL" - -if [ ${WORKERS+x} ] # We are on a CI worker -then - retry $RETRIES docker push $DOCKER_PUSH_IMAGE || echo "Push failed after $RETRIES retries" -else # We are in a local (non-CI) environment - docker push $DOCKER_PUSH_IMAGE || echo "You may need to run 'docker login' first and then re-run this script" -fi +echo "INFO: Pushing docker image $DOCKER_PUSH_IMAGE" +docker push "$DOCKER_PUSH_IMAGE" -readonly LATEST_TAG=$(git tag --list --sort=version:refname "v*" | grep -v - | cut -c2- | tail -n1) +# The latest (by semver version ordering) git version tag, with the 'v' removed. +readonly LATEST_GIT_TAG=$(git tag --list --sort=version:refname "v*" | grep -v - | cut -c2- | tail -n1) -if [ "$DOCKER_TAG" = "$LATEST_TAG" ] -then - echo "INFO: Current version ($DOCKER_TAG) is the latest version. Tagging and pushing $DOCKER_PUSH_IMAGE_LATEST ..." +if [[ "$DOCKER_TAG" == "$LATEST_GIT_TAG" ]]; then + echo "INFO: Docker tag '$DOCKER_TAG' matches latest git version tag, tagging and pushing $DOCKER_PUSH_IMAGE_LATEST" docker tag $DOCKER_PUSH_IMAGE $DOCKER_PUSH_IMAGE_LATEST - - if [ ${WORKERS+x} ] # We are on a CI worker - then - retry $RETRIES docker push $DOCKER_PUSH_IMAGE_LATEST || echo "Push failed after $RETRIES retries" - else # We are in a local (non-CI) environment - docker push $DOCKER_PUSH_IMAGE_LATEST || echo "You may need to run 'docker login' first and then re-run this script" - fi -fi \ No newline at end of file + docker push $DOCKER_PUSH_IMAGE_LATEST +fi