dev: Propose automating the monthly docs version bump - #2012
marcleblanc2 wants to merge 1 commit into
Conversation
One DOCS_VERSIONS list in docs.config.js written by a scheduled workflow from the release registry; a push-to-main workflow cuts the legacy branch and maps the Vercel domain; DNS pre-provisioned one major at a time. Amp-Thread-ID: https://ampcode.com/threads/T-01a0b2f1-85f6-717a-85a8-42fa0054fc68 Co-authored-by: Amp <amp@ampcode.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| registry knows which minors exist, Terraform knows which hosts exist, and | ||
| the legacy repo knows which snapshots exist. | ||
|
|
||
| The cut commit is not really a judgment call either: `v7_7` was branched |
There was a problem hiding this comment.
In this case, I think we picked the wrong commit. If we see 7.7.sourcegraph.com we see ABC now as GA where we should have probably picked f0addc6 where we still callout ABC as beta
| 2 maps it. The `versioned-docs-robots` Cloudflare worker reads the same | ||
| list, so the robots rule is covered too. This turns an Entitle grant plus PR | ||
| every month into one per year; a bot with standing write access to | ||
| `infrastructure` is the alternative and probably not worth the access. |
There was a problem hiding this comment.
I guess its not the end of the world if there's a unclaimed CNAME? Maybe Sec team has an opinion
| and loses a minor every few patch releases. A frozen host also has to pin | ||
| its own version, which the registry cannot tell it. | ||
|
|
||
| ### 2. Archive the previous version on merge (docs repo, two secrets) |
There was a problem hiding this comment.
See above but I think this is the biggest part of this. We don't really have a "develop" or "next" branch we consistently use for content that is coming up for the next version.
This means if we merge some cool new feature for 8.1 before the release actually happened, we'll now have that in the "old" 8.0.sourcegraph.com.
2 participants
Summary
Proposal to automate the monthly "Update docs latest version to X.Y" work, written up in
dev/versioning-proposal.md. No behaviour change in this PR; it is a draft for discussion.Today each minor takes five hand steps across four systems (infrastructure DNS PR behind an Entitle grant, cut and push a legacy branch, set its metadata, bump three files in this repo, map the domain in the Vercel dashboard). The three files here carry the same fact three times, the cut commit has in practice been the parent of the bump commit, and the release registry already knows which minors exist.
Proposed, in shippable order:
DOCS_VERSIONSlist indocs.config.js;src/data/versions.tsanddocs/legacy.mdxderive from it. A frozen branch then needs no metadata commit.pushtomainworkflow archives the previous version: pushHEAD^todocs-legacy-versionsasvP_Q, mapP.Q.sourcegraph.comthrough the Vercel API, verify, report to#alerts-vercel-doc-site.DOCS_VERSIONS[0].dns/sourcegraph.vercel.tfonce, instead of one minor per month.Net: monthly work becomes reading and merging one bot-opened PR; the Notion runbook and the
publishing-docs-versionsskill shrink accordingly.The list stays in the repo rather than being fetched at build time because
/v1/releases/sourcegraphcaps at the newest 50 releases with no paging (checkedlimit,page,offset), so it would lose old minors over time, and a frozen host has to pin its own version anyway.Open questions are at the bottom of the doc: selector scope (current and previous major vs today's 14 entries), whether "parent of the bump commit" is an acceptable default cut rule, and who owns the two new secrets.
Test plan
prettier --check,markdownlint-cli2andcspellclean on both files.git login this repo, thev7_7branch indocs-legacy-versions,dns/sourcegraph.vercel.tfininfrastructure, the release registry API, andhttps://7.7.sourcegraph.com/api/versions.