Skip to content

Commit 3d4878e

Browse files
ryanbas21ryanbas21
committed
chore: add-patch-release-docs-and-workflow
1 parent 8d50e40 commit 3d4878e

File tree

3 files changed

+185
-10
lines changed

3 files changed

+185
-10
lines changed

‎.github/workflows/ci.yml

Lines changed: 43 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,45 @@ jobs:
4444

4545
- run: pnpm exec playwright install
4646

47-
- uses: nrwl/nx-set-shas@v4
47+
- name: Get base and head SHAs for Nx affected commands
48+
id: get-shas
49+
run: |
50+
set -e # Exit immediately if a command exits with a non-zero status
51+
52+
# Check if 'gh' command is available
53+
if ! command -v gh &> /dev/null; then
54+
echo "Error: GitHub CLI (gh) is not installed." >&2
55+
exit 1
56+
fi
57+
58+
# Get latest release tag
59+
echo "Fetching latest GitHub release..."
60+
LATEST_RELEASE_TAG=$(gh release view --json tagName -q .tagName)
61+
62+
if [ -z "$LATEST_RELEASE_TAG" ]; then
63+
exit 1
64+
else
65+
echo "Latest release tag: $LATEST_RELEASE_TAG"
66+
# Get the commit SHA that this tag points to
67+
BASE_SHA=$(git rev-list -n 1 $LATEST_RELEASE_TAG)
68+
fi
69+
70+
# Get current HEAD SHA
71+
HEAD_SHA=$(git rev-parse HEAD)
72+
73+
echo "Base SHA (latest release): $BASE_SHA"
74+
echo "Head SHA (current): $HEAD_SHA"
75+
76+
# Set outputs for use with Nx
77+
echo "base_sha=$BASE_SHA" >> $GITHUB_OUTPUT
78+
echo "head_sha=$HEAD_SHA" >> $GITHUB_OUTPUT
79+
80+
# Export as environment variables for immediate use
81+
echo "NX_BASE=$BASE_SHA" >> $GITHUB_ENV
82+
echo "NX_HEAD=$HEAD_SHA" >> $GITHUB_ENV
83+
env:
84+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85+
4886
# This line is needed for nx affected to work when CI is running on a PR
4987
- run: git branch --track main origin/main
5088

@@ -68,13 +106,8 @@ jobs:
68106
- name: build docs
69107
run: pnpm generate-docs
70108

71-
- name: preview-docs
72-
uses: rajyan/preview-pages@v1
73-
with:
74-
source-dir: docs
75-
pr-comment: 'none'
76-
77-
- name: Update comment
78-
uses: marocchino/sticky-pull-request-comment@v2
109+
- name: Publish api docs
110+
uses: JamesIves/[email protected]
79111
with:
80-
message: Deployed ${{ github.sha }} to https://ForgeRock.github.io/ping-javascript-sdk/pr-${{ github.event.number }}/${{github.sha}} branch gh-pages in ForgeRock/ping-javascript-sdk
112+
folder: docs
113+
commit-message: 'chore: release-api-docs'

‎.github/workflows/patch-release.yml

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: Release Patch
2+
on:
3+
workflow_dispatch:
4+
inputs:
5+
branch-name:
6+
description: 'Name for the patch branch (typically like "patch-release-1.0.1")'
7+
required: true
8+
9+
env:
10+
NX_CLOUD_ENCRYPTION_KEY: ${{ secrets.NX_CLOUD_ENCRYPTION_KEY }}
11+
NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
12+
NX_CLOUD_DISTRIBUTED_EXECUTION: true
13+
PNPM_CACHE_FOLDER: .pnpm-store
14+
NPM_ACCESS_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
15+
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
16+
CI: true
17+
18+
jobs:
19+
create-and-publish-patch:
20+
permissions:
21+
contents: write # to create release (changesets/action)
22+
issues: write # to post issue comments (changesets/action)
23+
pull-requests: write # to create pull request (changesets/action)
24+
id-token: write # give id token write for provenance
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0
30+
token: ${{ secrets.GH_TOKEN }}
31+
32+
# Check out the provided branch - fail if it doesn't exist
33+
- name: Checkout patch branch
34+
run: |
35+
git checkout ${{ github.event.inputs.branch-name }}
36+
37+
# Setup environment
38+
- uses: pnpm/action-setup@v4
39+
with:
40+
run_install: false
41+
- uses: actions/setup-node@v4
42+
with:
43+
node-version: '22.14.0'
44+
cache: 'pnpm'
45+
46+
- run: pnpm install --frozen-lockfile
47+
48+
# This line enables distribution for NX
49+
- run: pnpm dlx nx-cloud start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yml" --stop-agents-after="e2e-ci" --with-env-vars="CODECOV_TOKEN"
50+
51+
- run: pnpm exec playwright install
52+
53+
- uses: nrwl/nx-set-shas@v4
54+
55+
- name: Setup pnpm config
56+
run: pnpm config set store-dir $PNPM_CACHE_FOLDER
57+
58+
- name: Version packages
59+
run: pnpm exec changeset version
60+
env:
61+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
62+
63+
# Build and test affected packages
64+
- name: Build and test
65+
run: pnpm exec nx affected -t build lint test e2e-ci
66+
67+
- name: Publish patch
68+
run: |
69+
echo "//registry.npmjs.org/:_authToken=$NPM_ACCESS_TOKEN" > .npmrc
70+
pnpm publish -r
71+
env:
72+
NPM_CONFIG_PROVENANCE: 'true'
73+
NPM_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
74+
75+
# Use changeset tag to create git tags according to changesets config
76+
- name: Create and push git tags
77+
run: |
78+
git config --global user.email "[email protected]"
79+
git config --global user.name "GitHub Actions"
80+
pnpm exec changeset tag
81+
git push --follow-tags
82+
83+
# Build and publish docs for the patch
84+
- name: Build docs
85+
run: pnpm generate-docs
86+
87+
- name: Publish api docs
88+
uses: JamesIves/[email protected]
89+
with:
90+
folder: docs
91+
commit-message: 'chore: release-api-docs-patch'

‎contributing_docs/releases.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,54 @@ We provide verdaccio two ways:
9595
topological graph.
9696

9797
- Publishing to a hosted private registry: Please message @ryanbas21 on slack.
98+
99+
# Patch Releases
100+
101+
In the event a patch release is required, we should always fix the bug on `main` before releasing any code.
102+
103+
This follows the trunk based development style of releasing which is best suited for changesets.
104+
105+
Once the bug is confirmed fixed, we can cherry-pick the fix from main, onto the latest release branch.
106+
107+
This cherry-pick should contain a changeset, if it does not, we will need to add one.
108+
109+
Once we have that new release branch confirmed working, and it has a changeset, we can push the branch to github.
110+
111+
We can then use the workflow_dispatch github workflow, called patch-release.yml, pass in the branch to release from as an input.
112+
113+
This will kickoff the release workflow, including building, testing, linting, etc.
114+
115+
Once passing, we will attempt to publish with provenance from CI (signing the packages).
116+
117+
It is worth noting that we could be on 1.0.1 on `npm` and our `main` branch may be on versions `1.0.0`. But because we push the tag up, changesets should respect the tag, and versions should be triggered based on the tag in the Release PR
118+
119+
## Patch Release Process
120+
121+
- Identify and fix the bug on main first
122+
This allows us to properly reproduce and verify the fix
123+
It ensures proper code review through your normal PR process
124+
The fix gets merged to main and will be included in future releases
125+
126+
- After the fix is merged to main, cherry-pick it to a patch branch
127+
128+
- Create a branch from the last release tag (e.g., v1.0.0)
129+
130+
- Cherry-pick the bugfix commit(s) from main to this patch branch
131+
132+
- Add a changeset file describing the patch change
133+
134+
- Push the patch branch and run the patch workflow
135+
136+
- This will publish the patch version (e.g., 1.0.1)
137+
138+
- No need to merge back to main
139+
140+
Since the fix already exists on main, there's no need to merge back
141+
This prevents any potential merge conflicts or duplication
142+
143+
This approach provides several benefits:
144+
145+
- Ensures the bug is properly identified and fixed first
146+
- Maintains normal code review process
147+
- Creates a clean git history with the fix clearly flowing from main to the patch branch
148+
- Avoids duplication of changes or complicated merge operations

0 commit comments

Comments
 (0)