From 4c0921ee6498f9355b4ac87343b6e7723628506b Mon Sep 17 00:00:00 2001 From: Marc Pichler Date: Mon, 4 Nov 2024 13:55:10 +0100 Subject: [PATCH] docs: update releasing.md to mention npm publish workflow, fix a link to release PR workflow (#5087) --- .github/workflows/publish-to-npm.yml | 10 ++++++++ doc/contributing/releasing.md | 38 +++++++++------------------- 2 files changed, 22 insertions(+), 26 deletions(-) diff --git a/.github/workflows/publish-to-npm.yml b/.github/workflows/publish-to-npm.yml index b51678268ab..e45e3d99a88 100644 --- a/.github/workflows/publish-to-npm.yml +++ b/.github/workflows/publish-to-npm.yml @@ -7,6 +7,7 @@ jobs: release-to-npm: runs-on: ubuntu-latest permissions: + # needed for NPM provenance id-token: write steps: - name: Checkout Repository @@ -22,10 +23,19 @@ jobs: - run: npm ci + # NOTE: in the past, we've had situations where the compiled files were missing as the `prepublishOnly` script was + # missing in some packages. `npx lerna publish` *should* also run compile, but this is intended as a safeguard + # when that does not happen for whatever reason. - run: npm run compile - name: Publish to npm env: NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}} NPM_CONFIG_PROVENANCE: true + # NOTE: using --concurrency 1 to reduce the likelihood of a race when publishing, + # which happens when the npm registry is not fully consistent yet. This can cause the publishing of a package to be + # rejected because dependencies are not available yet. `lerna` does ensure that this is not the case locally + # (packages are in-fact published in the correct order), but the race on the registry still applies. + # If this happens, run the workflow again - there should be enough time for everything to settle until this workflow + # attempts to publish again. run: npx lerna publish --concurrency 1 from-package --no-push --no-private --no-git-tag-version --no-verify-access --yes diff --git a/doc/contributing/releasing.md b/doc/contributing/releasing.md index 4a48995431c..18246c3cf88 100644 --- a/doc/contributing/releasing.md +++ b/doc/contributing/releasing.md @@ -3,9 +3,9 @@ This document is aimed at Maintainers and describes how to release a new version of the packages contained in this repository. We aim to eventually automate this process as much as possible. -## Create a release PR +## 1. Create a release PR -1. Go to the [Release PR Workflow](https://github.com/open-telemetry/opentelemetry-js/actions/workflows/create-or-update-release.yml) +1. Go to the [Release PR Workflow](https://github.com/open-telemetry/opentelemetry-js/actions/workflows/create-or-update-release-pr.yml) 2. Click "Run workflow" 3. For `Release Type`, select if you want to create a release PR for a new `minor` or `patch` version. 4. For `Release Scope`, select if you want to release @@ -18,37 +18,23 @@ We aim to eventually automate this process as much as possible. > If there was a commit to `main`, after PR creation simply run the workflow again before merging it. > Re-running it will update the PR with the contents from `main` and will update the PR body too. -## Review and merge the release PR +## 2. Review and merge the release PR 1. Review the PR generated via the workflow (it will be titled `chore: prepare next release` and opened by the @opentelemetrybot user) 2. Once approved, merge the PR -## Publish to NPM - -### Prerequisites - -1. Ensure you have access to the [`opentelemetry` npm organization](https://www.npmjs.com/org/opentelemetry) -2. Go to your npm user's `Access Tokens` page -3. Click `Generate New Token` -> `Granular Access Token` (2FA prompt will pop up) -4. Input all required fields - - recommended: set the expiry date on the token to 1 day - - recommended: set a CIDR range to only allow your IP -5. Under `Packages and Scopes` - - set `Permissions` to `Read and Write` - - Select `Only Select packages and scopes`, choose `@opentelemetry` - -### Publishing - -1. Check out the commit created by merging the release PR -2. run `git clean -fdx --exclude ` -3. run `npm ci` -4. run `npm run compile` -5. run `NODE_AUTH_TOKEN= npm run release:publish` +## 3. Publish to NPM > [!IMPORTANT] -> Delete the token once you're done publishing +> This step will publish anything that's on `main` IF AND ONLY IF the version has been bumped. If the version for a package +> has not been bumped, it will not publish a new version of the package. + +1. Go to the [NPM publish workflow](https://github.com/open-telemetry/opentelemetry-js/actions/workflows/publish-to-npm.yml) +2. Click "Run workflow" (from main) + 1. In rare cases not all packages are published due to a race when publishing, if you suspect this to + be the case, re-run the workflow: there should be enough time from 1. -## Create GitHub Releases +## 4. Create GitHub Releases 1. Check out the commit created by merging the release PR 2. Run