From 60fe37ea37f96272cfd846c8cde23c941ece7461 Mon Sep 17 00:00:00 2001 From: Aditi Abhang Date: Thu, 15 Oct 2026 19:28:47 +0000 Subject: [PATCH 1/3] skill: Cut legacy docs branches at the release publish time, not the main tip During the 8.1 cutover, v8_0 was cut from the origin/main tip (fb50b82b, #2090), which was merged six minutes after 8.1.0 was published and was marked "Merge after 8.1 releases". The skill told the agent to prefer the last commit on the release date or the tip, and never checked the actual release time. The cut-point section now uses the X.Y.0 publish time as a hard ceiling, lists docs PRs merged at or after it, flags PRs that may carry X.Y content (merge-after notes, post-branch-cut generated syncs, linked sourcegraph PRs on the X.Y.x branch), and requires the agent to propose the cut with evidence and wait for confirmation before creating or pushing the legacy branch. Amp-Thread-ID: https://ampcode.com/threads/T-01a140f9-34fa-726b-90c5-1608b2a7cc81 --- .../skills/publishing-docs-versions/SKILL.md | 72 +++++++++++++++---- 1 file changed, 60 insertions(+), 12 deletions(-) diff --git a/.agents/skills/publishing-docs-versions/SKILL.md b/.agents/skills/publishing-docs-versions/SKILL.md index 9ac05eb9b..9fe16ad20 100644 --- a/.agents/skills/publishing-docs-versions/SKILL.md +++ b/.agents/skills/publishing-docs-versions/SKILL.md @@ -37,29 +37,75 @@ Example: when 7.4 is released, archive 7.3 as `legacy/v7_3`, then update `origin ## Finding the cut point for a legacy branch -Always inspect history instead of guessing: +The archive for `P.Q` must not contain anything merged at or after the public +release of `X.Y`. The publish time is a hard ceiling, not a target: an earlier +hand-picked cut is fine when the reason is stated at the confirmation step. +Never default to the `origin/main` tip. + +1. Get the publish time of `X.Y.0` in UTC. Use the GitHub release; fall back to + the changelog API. Do not use the tag or `created_at`: the tag exists before + the release is public (7.7.0 was tagged 28 hours before it was published). + Also record when the `X.Y.x` release branch was cut from `main`. + +```bash +gh api repos/sourcegraph/sourcegraph/releases/tags/vX.Y.0 --jq '{published_at, created_at}' +curl -s 'https://sourcegraph.com/changelog/.api/search?q=X.Y.0' \ + | jq '.results[] | select(.type=="release-page" and .slug=="X.Y.0") | .release.sourcegraph | {promotedAt, gitSha}' +gh api repos/sourcegraph/sourcegraph/compare/main...X.Y.x --jq '.merge_base_commit.commit.committer.date' +``` + +2. Find the ceiling commit and the docs PRs the archive must exclude. Use the + full ISO timestamp; a date-only value widens the window. ```bash git fetch --all --prune -git log --date=short --pretty=format:'%h %ad %s' origin/main --since='' --until='' --reverse -git for-each-ref refs/remotes/legacy --format='%(refname:short) %(objectname:short) %(committerdate:short) %(subject)' | sort -V | tail -50 +PUBLISHED= +git log -1 --first-parent --before="$PUBLISHED" --date=iso-strict --format='%h %cd %s' origin/main +gh pr list --repo sourcegraph/docs --state merged --search "base:main merged:>=$PUBLISHED" --json number,title,mergedAt,mergeCommit +git for-each-ref refs/remotes/legacy --format='%(refname:short) %(objectname:short) %(committerdate:short)' | sort -V | tail -5 +``` + + `git merge-base --is-ancestor ` must fail for every PR + that list returns. + +3. Flag PRs merged between the release-branch cut date and the ceiling that may + carry `X.Y` content. Flagging is a signal for the user, not an automatic + exclusion. + +- Bodies or review comments saying "merge after X.Y releases", "hold until", or + "do not merge": + +```bash +gh pr list --repo sourcegraph/docs --state all --search "base:main updated:.." --json number,title,state,mergedAt,body +gh api repos/sourcegraph/docs/pulls//comments --jq '.[].body' ``` -Pick the commit the user considers the correct snapshot for the previous version. If the user gives a release date but not a commit, use the repo’s existing pattern: +- `πŸ€– Sync generated docs` PRs whose sync commit is dated after the release-branch + cut: their pages come from `main`, which is already the next version. +- PRs that link a `sourcegraph/sourcegraph` PR. If that PR's merge commit is on + `X.Y.x`, the docs PR documents an `X.Y` feature: + +```bash +gh api repos/sourcegraph/sourcegraph/compare/X.Y.x... --jq .status +``` -- Choose a hand-picked `origin/main` commit near the release cut. -- Prefer the last relevant docs commit on the release date when obvious. -- If no version-bump commit exists yet and the user wants the just-current docs archived, use the current `origin/main` tip. + `behind` means included. For `diverged`, search for a `[Backport X.Y.x]` PR + before concluding it is not. -For reference, recent historical decisions: +4. Propose and wait. Post the publish time and its source, the ceiling commit, + the excluded PRs, each flagged PR with its reason, and the proposed cut. If + the proposed cut is earlier than the ceiling, say why. Stop until the user + confirms the commit. Do not create or push the legacy branch before that. -- `legacy/v7_0` was cut from `a5d80e5e` and then got empty no-op marker commits. -- `legacy/v7_1` was cut from `6b8ae421` for the Apr 24 release-date snapshot. -- `legacy/v7_2` was cut from `fccceac6`, then updated with a version metadata commit. +Example: `v8_0` was first cut from the `origin/main` tip `fb50b82b` (#2090, +"Merge after 8.1 releases", merged six minutes after 8.1.0 was published) and +re-cut from `ddfe8c2`. The ceiling was `5e5bb56`; `ddfe8c2` also left out #2078 +(documents sourcegraph#16774, which is on `8.1.x`) and the post-cut sync #2071. ## Creating and pushing the legacy branch -Create the branch from the selected cut commit, add an empty marker commit, and push to `legacy`: +Only after the user confirmed the cut commit. Create the branch from it, add an +empty marker commit, and push to `legacy`: ```bash git switch --detach @@ -130,6 +176,8 @@ git ls-remote --heads legacy 'v7_*' Confirm: - The legacy branch points to the pushed commit. +- No docs PR merged at or after the `X.Y.0` publish time is an ancestor of the + legacy branch. - The legacy branch identifies itself without claiming to be latest and lists only older fallback versions. - The origin PR branch sets the new latest version and includes the archived version in previous-version lists. From 0c45cf4e0e2e3b1cb36a167fca6b1ef1e6de44b1 Mon Sep 17 00:00:00 2001 From: Aditi Abhang Date: Thu, 15 Oct 2026 19:33:21 +0000 Subject: [PATCH 2/3] skill: Tighten cut-point wording Amp-Thread-ID: https://ampcode.com/threads/T-01a140f9-34fa-726b-90c5-1608b2a7cc81 --- .../skills/publishing-docs-versions/SKILL.md | 64 ++++++++----------- 1 file changed, 28 insertions(+), 36 deletions(-) diff --git a/.agents/skills/publishing-docs-versions/SKILL.md b/.agents/skills/publishing-docs-versions/SKILL.md index 9fe16ad20..6d599f004 100644 --- a/.agents/skills/publishing-docs-versions/SKILL.md +++ b/.agents/skills/publishing-docs-versions/SKILL.md @@ -37,42 +37,37 @@ Example: when 7.4 is released, archive 7.3 as `legacy/v7_3`, then update `origin ## Finding the cut point for a legacy branch -The archive for `P.Q` must not contain anything merged at or after the public -release of `X.Y`. The publish time is a hard ceiling, not a target: an earlier -hand-picked cut is fine when the reason is stated at the confirmation step. -Never default to the `origin/main` tip. +Nothing merged at or after the public release of `X.Y` may be in the `P.Q` +archive. The publish time is a hard ceiling, not a target. Never default to the +`origin/main` tip. -1. Get the publish time of `X.Y.0` in UTC. Use the GitHub release; fall back to - the changelog API. Do not use the tag or `created_at`: the tag exists before - the release is public (7.7.0 was tagged 28 hours before it was published). - Also record when the `X.Y.x` release branch was cut from `main`. +1. Get the `X.Y.0` publish time (UTC) and the `X.Y.x` branch cut date. Use the + publish time, not the tag time: 7.7.0 was tagged 28 hours before it was + published. ```bash gh api repos/sourcegraph/sourcegraph/releases/tags/vX.Y.0 --jq '{published_at, created_at}' -curl -s 'https://sourcegraph.com/changelog/.api/search?q=X.Y.0' \ - | jq '.results[] | select(.type=="release-page" and .slug=="X.Y.0") | .release.sourcegraph | {promotedAt, gitSha}' +# fallback +curl -s 'https://sourcegraph.com/changelog/.api/search?q=X.Y.0' | jq '.results[] | select(.slug=="X.Y.0") | .release.sourcegraph.promotedAt' gh api repos/sourcegraph/sourcegraph/compare/main...X.Y.x --jq '.merge_base_commit.commit.committer.date' ``` -2. Find the ceiling commit and the docs PRs the archive must exclude. Use the - full ISO timestamp; a date-only value widens the window. +2. Find the ceiling commit and the PRs the archive must exclude. Use the full + ISO timestamp. ```bash git fetch --all --prune PUBLISHED= git log -1 --first-parent --before="$PUBLISHED" --date=iso-strict --format='%h %cd %s' origin/main gh pr list --repo sourcegraph/docs --state merged --search "base:main merged:>=$PUBLISHED" --json number,title,mergedAt,mergeCommit -git for-each-ref refs/remotes/legacy --format='%(refname:short) %(objectname:short) %(committerdate:short)' | sort -V | tail -5 ``` - `git merge-base --is-ancestor ` must fail for every PR - that list returns. + `git merge-base --is-ancestor ` must fail for each PR listed. -3. Flag PRs merged between the release-branch cut date and the ceiling that may - carry `X.Y` content. Flagging is a signal for the user, not an automatic - exclusion. +3. Flag PRs merged between the branch cut date and the ceiling that may carry + `X.Y` content. Flags are for the user to decide, not automatic exclusions. -- Bodies or review comments saying "merge after X.Y releases", "hold until", or +- Body or review comments saying "merge after X.Y releases", "hold until", or "do not merge": ```bash @@ -80,32 +75,29 @@ gh pr list --repo sourcegraph/docs --state all --search "base:main updated:/comments --jq '.[].body' ``` -- `πŸ€– Sync generated docs` PRs whose sync commit is dated after the release-branch - cut: their pages come from `main`, which is already the next version. -- PRs that link a `sourcegraph/sourcegraph` PR. If that PR's merge commit is on - `X.Y.x`, the docs PR documents an `X.Y` feature: +- `πŸ€– Sync generated docs` PRs dated after the branch cut: they come from `main`, + which is already the next version. +- PRs linking a `sourcegraph/sourcegraph` PR whose merge commit is on `X.Y.x` + (`behind` = included; for `diverged`, check for a `[Backport X.Y.x]` PR): ```bash gh api repos/sourcegraph/sourcegraph/compare/X.Y.x... --jq .status ``` - `behind` means included. For `diverged`, search for a `[Backport X.Y.x]` PR - before concluding it is not. +4. Propose and wait. Post the publish time and source, ceiling commit, excluded + PRs, flagged PRs with reasons, and the proposed cut (with a reason if it is + below the ceiling). Do not create or push the legacy branch until the user + confirms. -4. Propose and wait. Post the publish time and its source, the ceiling commit, - the excluded PRs, each flagged PR with its reason, and the proposed cut. If - the proposed cut is earlier than the ceiling, say why. Stop until the user - confirms the commit. Do not create or push the legacy branch before that. - -Example: `v8_0` was first cut from the `origin/main` tip `fb50b82b` (#2090, -"Merge after 8.1 releases", merged six minutes after 8.1.0 was published) and -re-cut from `ddfe8c2`. The ceiling was `5e5bb56`; `ddfe8c2` also left out #2078 -(documents sourcegraph#16774, which is on `8.1.x`) and the post-cut sync #2071. +Example: `v8_0` was first cut from the tip `fb50b82b` (#2090, "Merge after 8.1 +releases", merged six minutes after 8.1.0 was published), then re-cut from +`ddfe8c2`. Ceiling was `5e5bb56`; `ddfe8c2` also excluded #2078 (documents +sourcegraph#16774, on `8.1.x`) and the post-cut sync #2071. ## Creating and pushing the legacy branch -Only after the user confirmed the cut commit. Create the branch from it, add an -empty marker commit, and push to `legacy`: +After the user confirms the cut commit, create the branch, add an empty marker +commit, and push to `legacy`: ```bash git switch --detach From 44e27ecb101cbd8e205d7ff4e7a695066ec3d928 Mon Sep 17 00:00:00 2001 From: Aditi Abhang Date: Thu, 15 Oct 2026 19:41:04 +0000 Subject: [PATCH 3/3] skill: Restore history commands and nest code blocks under steps Amp-Thread-ID: https://ampcode.com/threads/T-01a140f9-34fa-726b-90c5-1608b2a7cc81 --- .../skills/publishing-docs-versions/SKILL.md | 52 ++++++++++--------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/.agents/skills/publishing-docs-versions/SKILL.md b/.agents/skills/publishing-docs-versions/SKILL.md index 6d599f004..f15d974fb 100644 --- a/.agents/skills/publishing-docs-versions/SKILL.md +++ b/.agents/skills/publishing-docs-versions/SKILL.md @@ -45,44 +45,46 @@ archive. The publish time is a hard ceiling, not a target. Never default to the publish time, not the tag time: 7.7.0 was tagged 28 hours before it was published. -```bash -gh api repos/sourcegraph/sourcegraph/releases/tags/vX.Y.0 --jq '{published_at, created_at}' -# fallback -curl -s 'https://sourcegraph.com/changelog/.api/search?q=X.Y.0' | jq '.results[] | select(.slug=="X.Y.0") | .release.sourcegraph.promotedAt' -gh api repos/sourcegraph/sourcegraph/compare/main...X.Y.x --jq '.merge_base_commit.commit.committer.date' -``` + ```bash + gh api repos/sourcegraph/sourcegraph/releases/tags/vX.Y.0 --jq '{published_at, created_at}' + # fallback + curl -s 'https://sourcegraph.com/changelog/.api/search?q=X.Y.0' | jq '.results[] | select(.slug=="X.Y.0") | .release.sourcegraph.promotedAt' + gh api repos/sourcegraph/sourcegraph/compare/main...X.Y.x --jq '.merge_base_commit.commit.committer.date' + ``` 2. Find the ceiling commit and the PRs the archive must exclude. Use the full ISO timestamp. -```bash -git fetch --all --prune -PUBLISHED= -git log -1 --first-parent --before="$PUBLISHED" --date=iso-strict --format='%h %cd %s' origin/main -gh pr list --repo sourcegraph/docs --state merged --search "base:main merged:>=$PUBLISHED" --json number,title,mergedAt,mergeCommit -``` + ```bash + git fetch --all --prune + git log --date=short --pretty=format:'%h %ad %s' origin/main --since='' --until='' --reverse + git for-each-ref refs/remotes/legacy --format='%(refname:short) %(objectname:short) %(committerdate:short) %(subject)' | sort -V | tail -50 + PUBLISHED= + git log -1 --first-parent --before="$PUBLISHED" --date=iso-strict --format='%h %cd %s' origin/main + gh pr list --repo sourcegraph/docs --state merged --search "base:main merged:>=$PUBLISHED" --json number,title,mergedAt,mergeCommit + ``` `git merge-base --is-ancestor ` must fail for each PR listed. 3. Flag PRs merged between the branch cut date and the ceiling that may carry `X.Y` content. Flags are for the user to decide, not automatic exclusions. -- Body or review comments saying "merge after X.Y releases", "hold until", or - "do not merge": + - Body or review comments saying "merge after X.Y releases", "hold until", or + "do not merge": -```bash -gh pr list --repo sourcegraph/docs --state all --search "base:main updated:.." --json number,title,state,mergedAt,body -gh api repos/sourcegraph/docs/pulls//comments --jq '.[].body' -``` + ```bash + gh pr list --repo sourcegraph/docs --state all --search "base:main updated:.." --json number,title,state,mergedAt,body + gh api repos/sourcegraph/docs/pulls//comments --jq '.[].body' + ``` -- `πŸ€– Sync generated docs` PRs dated after the branch cut: they come from `main`, - which is already the next version. -- PRs linking a `sourcegraph/sourcegraph` PR whose merge commit is on `X.Y.x` - (`behind` = included; for `diverged`, check for a `[Backport X.Y.x]` PR): + - `πŸ€– Sync generated docs` PRs dated after the branch cut: they come from `main`, + which is already the next version. + - PRs linking a `sourcegraph/sourcegraph` PR whose merge commit is on `X.Y.x` + (`behind` = included; for `diverged`, check for a `[Backport X.Y.x]` PR): -```bash -gh api repos/sourcegraph/sourcegraph/compare/X.Y.x... --jq .status -``` + ```bash + gh api repos/sourcegraph/sourcegraph/compare/X.Y.x... --jq .status + ``` 4. Propose and wait. Post the publish time and source, ceiling commit, excluded PRs, flagged PRs with reasons, and the proposed cut (with a reason if it is