| name | docs-website-update |
| description | Sync docs commits from `master` out to the live docs branches in the nx repo: cherry-picks `docs(` / `feat(nx-dev)` commits onto `website-<major>` AND the latest `<major>.<minor>.x` release branch. Use when "update the docs branch", "update nx.dev", "push the latest docs changes out", "cherry-pick docs commits", "sync website-23", "ship docs to the website branch", "update the docs website", "get docs onto the release branch", or any request to move already-merged docs commits from master onto the branches that deploy them. |
Update Docs Website
This skill works in the nx repo only.
CRITICAL:
- If you are not in the
nx repo, say so and stop working!
- If there are uncommitted/untracked files, say so and stop working!
Why two branches
Docs commits must land on BOTH:
website-<major> (e.g. website-23) - deploys nx.dev for the current major- the latest release branch
<major>.<minor>.x (e.g. 23.1.x) - used for patch releases, and the release pipeline overwrites the website-<major> branch from it
If only website-23 gets the commit, the next patch release from 23.1.x wipes it.
How to Update
1. Determine the branches
git fetch origin master
git fetch origin 'refs/heads/website-*:refs/remotes/origin/website-*'
git fetch origin 'refs/heads/*.x:refs/remotes/origin/*.x'
- Website branch: highest
origin/website-<N> where <N> is an integer.
Exclude website-master and any branch with extra path segments (e.g. website-19-cherry-01/...).
git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/website-*' \
| grep -E '^origin/website-[0-9]+$' | sort -V | tail -1
- Release branch: highest
origin/<N>.<minor>.x with the SAME major <N> as the website branch.
git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/*.x' \
| grep -E "^origin/${MAJOR}\.[0-9]+\.x$" | sort -V | tail -1
If no release branch exists for that major, say so and continue with the website branch only.
Report both branch names before doing any work.
2. Sync the branches
git checkout master && git reset --hard origin/master
git checkout <website-branch> && git reset --hard origin/<website-branch>
git checkout <release-branch> && git reset --hard origin/<release-branch>
3. Build the cherry-pick list (from the website branch)
- On
<website-branch>, get the last commit subject -> /tmp/last-website-commit.txt
- Back on
master, find the commit whose subject matches /tmp/last-website-commit.txt -> sha in /tmp/last-master-sha.txt
- On
master, list commits between that sha and HEAD, filtered to subjects starting with docs( or feat(nx-dev) -> /tmp/commits-to-cherry-pick.txt (oldest at bottom, as git log prints it)
4. Cherry-pick onto the website branch
On <website-branch>, oldest to newest:
git cherry-pick <sha>
- On failure: record in
/tmp/failed-website.txt, git cherry-pick --abort, move on.
- If the pick is empty (already applied):
git cherry-pick --skip, record as skipped.
5. Cherry-pick the SAME list onto the release branch
The release branch was cut from master at a different point, so some commits may already be there.
- Skip any commit whose subject already appears in the release branch's log:
git log <release-branch> --format='%s' | grep -Fxq "<subject>"
- Cherry-pick the rest oldest to newest, same rules as step 4.
- Failures ->
/tmp/failed-release.txt
- Empty picks ->
git cherry-pick --skip
Conflicts are more likely here than on the website branch - do NOT try to resolve them, just abort and report.
6. Report
Print a per-branch breakdown:
| Branch | Cherry-picked | Already present / skipped | Failed |
|---|
List failed shas with subjects so they can be handled manually.
Do NOT push. End by reminding which branches have unpushed commits, e.g.:
git push origin website-23
git push origin 23.1.x
