docs: update releasing.md to mention npm publish workflow, fix a link to release PR workflow (#5087)

.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

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 <whatever you want to keep, e.g. .idea, .vscode>`
-3. run `npm ci`
-4. run `npm run compile`
-5. run `NODE_AUTH_TOKEN=<token generated earlier> 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.
 
-## Create GitHub Releases
+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.
+
+## 4. Create GitHub Releases
 
 1. Check out the commit created by merging the release PR
 2. Run