Skip to content

Commit 25ec15b

Browse files
ancheetahancheetah
committed
chore: update release documentation
1 parent e239060 commit 25ec15b

2 files changed

Lines changed: 113 additions & 43 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 52 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,28 @@ on:
55
- main
66
workflow_dispatch:
77
inputs:
8-
branch:
9-
description: 'Branch/ref to publish from'
10-
required: false
11-
default: 'main'
12-
type: string
13-
dist_tag:
14-
description: 'npm dist-tag'
8+
snapshot_tag:
9+
description: 'changesets snapshot tag (beta/canary)'
1510
required: false
1611
default: 'beta'
1712
type: string
18-
prerelease:
19-
description: 'changesets prerelease tag (beta/canary)'
13+
npm_tag:
14+
description: 'npm dist-tag for publishing snapshot'
2015
required: false
2116
default: 'beta'
2217
type: string
23-
access:
24-
description: 'npm access'
18+
npm_access:
19+
description: 'access level for publishing snapshot to npm'
2520
required: false
2621
default: 'public'
27-
type: string
22+
type: choice
23+
options:
24+
- public
25+
- restricted
2826
env:
2927
NX_CLOUD_ENCRYPTION_KEY: ${{ secrets.NX_CLOUD_ENCRYPTION_KEY }}
3028
NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
29+
SLACK_WEBHOOK_URL_BETA: ${{ secrets.SLACK_WEBHOOK_URL_BETA }}
3130
PNPM_CACHE_FOLDER: .pnpm-store
3231
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
3332
CI: true
@@ -97,7 +96,7 @@ jobs:
9796

9897
snapshot:
9998
if: ${{ github.event_name == 'workflow_dispatch' }}
100-
name: Publish Snapshots
99+
name: Publish snapshot/beta to npm
101100
permissions:
102101
contents: write
103102
id-token: write
@@ -107,22 +106,55 @@ jobs:
107106
env:
108107
HUSKY: 0
109108
steps:
110-
- uses: actions/checkout@v4
109+
- name: Branch name
110+
run: |
111+
echo "Checking out branch: ${{ github.ref_name }}"
112+
113+
# Checkout the branch selected when triggering the workflow
114+
- name: Checkout repository
115+
uses: actions/checkout@v4
111116
with:
112117
fetch-depth: 0
113118
token: ${{ secrets.GH_TOKEN }}
114-
ref: ${{ inputs.branch }}
115119

116120
- name: Setup Project
117121
uses: ./.github/actions/setup
118122
with:
119123
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
120124

121-
- name: Version Packages as prerelease
122-
run: pnpm changeset version --snapshot ${{ inputs.prerelease }}
125+
- name: Version Packages for snapshot
126+
run: pnpm changeset version --snapshot ${{ inputs.snapshot_tag }}
123127
env:
124128
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
125129

126-
# The actual npm publish that must occur in the authorized file
127-
- name: Publish packages with dist-tag
128-
run: pnpm publish -r --tag ${{ inputs.dist_tag }} --no-git-checks --access ${{ inputs.access }}
130+
- name: Publish packages snapshot with npm_tag
131+
id: npmpublish
132+
run: pnpm publish -r --tag ${{ inputs.npm_tag }} --no-git-checks --access ${{ inputs.npm_access }}
133+
134+
- name: Format published packages for Slack
135+
if: steps.npmpublish.outcome == 'success'
136+
id: format-packages
137+
env:
138+
NPM_TAG: ${{ inputs.npm_tag }}
139+
SNAPSHOT_TAG: ${{ inputs.snapshot_tag }}
140+
run: |
141+
FORMATTED=$(jq -rs --arg tag "$SNAPSHOT_TAG" '[.[] | select(.version | contains($tag))] | .[] | ":package: *\(.name)* `\(.version)`"' packages/*/package.json)
142+
PAYLOAD=$(jq -n --arg packages "$FORMATTED" --arg npmTag "$NPM_TAG" '{"npmTag": $npmTag, "publishedPackages": $packages}')
143+
echo "payload<<EOF" >> $GITHUB_OUTPUT
144+
echo "$PAYLOAD" >> $GITHUB_OUTPUT
145+
echo "EOF" >> $GITHUB_OUTPUT
146+
147+
- name: Send GitHub Action data to a Slack workflow
148+
if: steps.npmpublish.outcome == 'success'
149+
id: slack-notify-beta
150+
continue-on-error: true
151+
uses: slackapi/slack-github-action@v2.1.1
152+
with:
153+
webhook: ${{ env.SLACK_WEBHOOK_URL_BETA }}
154+
webhook-type: webhook-trigger
155+
payload: ${{ steps.format-packages.outputs.payload }}
156+
157+
- name: Warn if Slack notification failed
158+
if: steps.slack-notify-beta.outcome == 'failure'
159+
run: |
160+
echo "::warning::Slack beta notification failed. Check the webhook URL and payload format."

‎contributing_docs/releases.md‎

Lines changed: 61 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@ We use changesets to handle publishing of all packages in the repository.
44
Please see the changesets repository for documentation on how to use
55
changesets. Below will be a brief summary.
66

7+
## Table of Contents
8+
9+
- [Adding a changeset](#adding-a-changeset)
10+
- [Versioning](#versioning)
11+
- [Adding a package to the repository](#adding-a-package-to-the-repository)
12+
- [Testing a package publish](#testing-a-package-publish)
13+
- [First time releasing a package](#first-time-releasing-a-package)
14+
- [Publishing a beta](#publishing-a-beta)
15+
716
## Adding a changeset
817

918
You can run `pnpm changeset` in order to add a changeset. You then
@@ -55,43 +64,72 @@ This is common for `e2e` related applications. We don't version or care
5564
about publishing them. You will see in the `.changesets/config.json` these are listed
5665
in the `ignore` field, and they will all have `private:true` in the package.json
5766

67+
## Testing a package publish
68+
69+
In order to test a package publish, you should use `verdaccio`.
70+
71+
We provide verdaccio two ways:
72+
73+
1. `pnpm nx run local-registry`. This command will spawn a private npm registry. It also _should_ update your local `.npmrc` file to point here.
74+
75+
You can then publish your package like so:
76+
77+
```bash
78+
pnpm changeset version
79+
pnpm publish packages/{your_package} --dry-run --no-git-checks --registry=http://localhost:4873
80+
```
81+
82+
**Notes**:
83+
- The `changeset` command will version your packages before the test release. To version them as a beta add `--snapshot beta` to the changeset command
84+
- I am including the `dry-run` flag here so if you copy paste it, you will "dry-run" the publish.
85+
- I also like to add the `registry` flag, as a secondary check to make sure I publish to this registry.
86+
- The `-r` flag is necessary if your package requires other workspace packages to be published. This command runs `publish` recursively via pnpm's topological graph. To publish all packages, include the `-r` flag and remove `packages/{yourpackage}` from the publish command.
87+
- Include the `--no-git-checks` flag to ignore the changes made by the versioning command
88+
- To test publish a beta, add `--tag beta`
89+
- If you are publishing from a branch other than `main`, add `--publish-branch {branch-name}`
90+
91+
2. Publishing to a hosted private registry: Please message `@ryan.basmajian` on Slack.
92+
5893
## First time releasing a package
5994

60-
If your package is ready to be released, and has never been released before,
61-
(the package.json `name` field does not exist on `npm`), then it is critical that
62-
your `{packageRoot}/package.json` has the following:
95+
If your package is ready to be released, and has never been released before, (the package.json `name` field does not exist on `npm`), then it is critical that the package be published manually as a beta first.
6396

64-
```
97+
First ensure that the `{packageRoot}/package.json` has the following:
98+
99+
```json
65100
"publishConfig": {
66101
"access": "public"
67102
}
68103
```
69104

70-
If your package does not contain this information, your package publishing **WILL**
71-
break the publish pipeline.
105+
When the package is officially ready for release, you should also delete the `private: true` from the `{projectRoot}/package.json`.
72106

73-
This is because all packages in this repository are published with `npm provenance`.
74-
You can read about the requirements [here](https://docs.npmjs.com/generating-provenance-statements#prerequisites).
107+
Then publish the package to npm:
75108

76-
## Testing a package publish
109+
```bash
110+
# Version packages for beta
111+
pnpm changeset version --snapshot beta
112+
# Check that the beta tag is correct in a dry run
113+
pnpm publish <package-name> --tag beta --no-git-checks --access public --dry-run
114+
# Publish beta for the first time
115+
pnpm publish <package-name> --tag beta --no-git-checks --access public
116+
```
77117

78-
In order to test a package publish, you should use `verdaccio`.
118+
If you do not do this, your package publishing **WILL** break the publish pipeline. Publishing manually first prevents the package being published as the default private.
79119

80-
We provide verdaccio two ways:
120+
Next set up provenance and trusted publishing. With trusted publishing enabled, provenance attestations will be generated automatically. Learn more [here](https://docs.npmjs.com/trusted-publishers#automatic-provenance-generation).
121+
122+
To set up trusted publishing, follow the instructions [here](https://docs.npmjs.com/trusted-publishers#for-github-actions). Configure the following fields:
81123

82-
- `pnpm nx run local-registry`. This command will spawn a private npm registry.
83-
It also _should_ update your local `.npmrc` file to point here.
124+
- **Publisher**: GitHub Actions
125+
- **Organization**: ForgeRock
126+
- **Repository**: ping-javascript-sdk
127+
- **Workflow filename**: publish.yml
84128

85-
You can then publish your package like so:
129+
Additionally, set the publishing access to `Require two-factor authentication and disallow tokens`.
86130

87-
```bash
88-
pnpm publish packages/{your_package} --dry-run --registry=http://localhost:4873
89-
```
131+
You should now be able to publish with provenance from GitHub Actions. To learn how to publish a beta from GitHub Actions see the next section [Publishing a beta](#publishing-a-beta) below.
90132

91-
Notes: - I am including the `dry-run` flag here so if you copy paste it,
92-
you will "dry-run" the publish. - I also like to add the `registry` flag, as a secondary check to
93-
make sure i publish to this registry. - The `-r` flag is necessary if your package requires other workspace packages
94-
to be published. This command runs `publish` recursively via pnpm's
95-
topological graph.
133+
## Publishing a beta
96134

97-
- Publishing to a hosted private registry: Please message @ryanbas21 on slack.
135+
You can trigger a beta publish manually via the `publish.yml` GitHub action. In GitHub, select the `Actions` tab then the `Publish` workflow. Then select the `Run workflow` dropdown on the right-hand side. Select the branch you want to release in the `Use workflow from` dropdown, then fill out the beta release options. Click `Run workflow` and the action will automatically release the changeset snapshot to npm.

0 commit comments

Comments
 (0)