docs-website-update

# 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 The `+` on each refspec is required. A release force-pushes `website-<major>` from the release branch, so a non-forced fetch is rejected as non-fast-forward and leaves `origin/website-<major>` pointing at the pre-release commit. ```bash git fetch origin '+refs/heads/master:refs/remotes/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/...`). ```bash 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. ```bash 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. Confirm the remote-tracking refs actually match the remote before touching them: ```bash git ls-remote origin refs/heads/<website-branch> refs/heads/<release-branch> git rev-parse origin/<website-branch> origin/<release-branch> ``` If the shas differ, the fetch did not take - stop and re-fetch. Every later step (the anchor commit, the cherry-pick list, any conflict) is wrong otherwise. Report both branch names before doing any work. ### 2. Sync the branches ```bash 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) 1. On `<website-branch>`, get the last commit subject -> `/tmp/last-website-commit.txt` 2. Back on `master`, find the commit whose subject matches `/tmp/last-website-commit.txt` -> sha in `/tmp/last-master-sha.txt` 3. 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: ```bash 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. 1. Skip any commit whose subject already appears in the release branch's log: ```bash git log <release-branch> --format='%s' | grep -Fxq "<subject>" ``` 2. 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 ```