Files
coder/scripts/releaser/docs.go
T
Nick Vigilante d5a6047879 docs: restructure Install into the five phase deployment spine (#29304)
Restructures the Install section into the five-phase deployment spine,
so the reading order matches the order a deployment actually happens:
**plan, prepare, install, validate, operate.** Today the first thing a
reader sees is a shell command, and architecture and sizing sit
downstream in Administration, after the point where they would have been
useful.

Resolves [DOCS-869](https://linear.app/codercom/issue/DOCS-869). Part of
[DOCS-685](https://linear.app/codercom/issue/DOCS-685) and
[DOCS-738](https://linear.app/codercom/issue/DOCS-738).

> [!IMPORTANT]
> **Stacked on [#28960](https://github.com/coder/coder/pull/28960)**
(DOCS-871, terminology). Base is that branch, not `main`. Retarget to
`main` after it merges.
>
> **Paired with coder/coder.com
[#1077](https://github.com/coder/coder.com/pull/1077)**, which must
merge **first**. Without it, every inbound link to a moved page 404s in
the gap.

## Deliberately mechanical

No prose changes. The only edits inside moved pages are relative link
and image path repairs, so the diff reads as renames. That is the point:
this is the highest link-breakage change in the project, and it should
be reviewable as such.

The prose work is [DOCS-868](https://linear.app/codercom/issue/DOCS-868)
(phase overview, architecture rewrite, sizing split, actor table) and
[DOCS-872](https://linear.app/codercom/issue/DOCS-872) (new pages).

## The new spine

```text
Install and deploy Coder            /install
├── Coder CLI                                   [unchanged, retired by DOCS-870]
├── 1. Plan your deployment
│   ├── Architecture and components             [from admin/infrastructure]
│   └── Coder Validated Architecture            [from admin/infrastructure]
│       └── 1k / 2k / 3k / 10k users
├── 2. Prepare prerequisites
│   ├── Licensing                               [from admin/licensing]
│   ├── Air-gapped deployments                  [from install/airgap]
│   └── Mirror images and registries            [from install/registry-mirror-artifactory]
├── 3. Install the control plane
│   ├── Docker / Kubernetes / Rancher / OpenShift
│   ├── Cloud marketplace and VM images
│   └── Unofficial install methods
├── 4. Validate your deployment
│   └── Scale testing                           [from admin/infrastructure]
│       ├── Scale test utility
│       └── Scaling best practices
└── 5. Operate and maintain
    ├── External provisioners                   [from admin/provisioners]
    ├── Upgrading (+ best practices, ESR guides)
    └── Uninstall
```

Leaving Install: release channels become `reference/releases`, feature
stages become `reference/feature-stages`.

`docs/admin/infrastructure/` is gone entirely, which is what DOCS-738
recommended.

## Numbers

- 31 pages moved, all as `git mv` renames.
- 1 page deleted: `admin/infrastructure/index.md`, whose content was a
one-line section blurb.
- 5 new placeholder index pages, one per phase, each a sentence of
orientation plus `<children></children>`. The nav schema requires a path
on every entry, so a phase cannot exist without one.
- 265 relative links and asset paths repaired across 57 files.
- `docs/manifest.json` restructured. Entry count goes 460 to 464: plus 5
stubs, minus the deleted Infrastructure entry.

## Reviewer attention, please

**The redirects PR repairs 19 existing redirects, not just adds new
ones.** This was the surprise. `redirects.json` already had entries
whose *destinations* pointed at pages this PR moves, so they would have
started redirecting to 404s. Examples:
`/docs/architecture/architecture`, `/docs/admin/architectures`,
`/docs/scaling/scale-testing`, `/docs/licensing`, `/docs/enterprise`,
`/docs/install/offline`, `/docs/platforms`, `/docs/install/1-click`,
`/docs/admin/upgrade`, `/docs/install/cloud/ec2`, and both
`feature-stages` aliases. All 19 are fixed in the paired PR.

**This PR touches `scripts/`, so it is not docs-only.** Two release
tools write to paths that moved and would have broken silently at
release time:

- `scripts/update-release-calendar.sh`: `DOCS_FILE` now points at
`docs/reference/releases.md`.
- `scripts/releaser/docs.go`: `releasesFile`, and also `kubernetesFile`
and `rancherFile`, which pointed at `docs/install/kubernetes.md` and
`docs/install/rancher.md`.

<details>
<summary>Deliberate scope decisions</summary>

- **Self-managed vs cloud grouping is flattened.** The reconciled IA
nested platform pages under a "Self-managed platforms" parent. That
would need two more placeholder index pages for groups with no content
yet, so the platform pages sit directly under Phase 3 and the grouping
lands with the DOCS-868 prose.
- **Release-notes URLs left alone.** `scripts/releaser/release.go` and
`scripts/release/generate_release_notes.sh` embed
`https://coder.com/docs/install/releases` and `/docs/install/upgrade` in
release-note templates. The redirects cover them, and changing the
strings would require updating Go test fixtures in
`scripts/release/main_internal_test.go`. Better as its own change.
- **In-product doc links left alone.** Several `site/src` pages link to
`coder.com/docs/admin/provisioners` and similar. Those are absolute
URLs, so the redirects cover them. Updating them is a frontend change
that would pull frontend review into a docs restructure.
- **`admin/security/audit-logs.md` line 237** is hand-written prose
below the generated table, and its `../licensing/index.md` link had to
move with the licensing page. Verified `make gen` does not revert it.
- **`reference/feature-stages.md`** has generated blocks whose relative
links changed depth with the move. The generator named in its own marker
comment (`scripts/release/docs_update_feature_stages.sh`) no longer
exists in the repo, so those links were repaired by hand and the file is
effectively hand-maintained. Worth its own issue.
- **`install/cli.md` keeps its nav slot** here. DOCS-870 retires it.

</details>

## Verification

| Check | Result |
|---|---|
| Broken relative link scan | 0 in `install/`, `admin/`, `reference/`.
21 remain, all pre-existing illustrative examples in
`docs/.style/style-guide/**` and one malformed URL in `docs/README.md` |
| `make gen` | clean, manifest not clobbered, phase structure intact |
| `make lint/markdown` | pass, 508 files, 0 errors |
| `make lint/emdash` | pass |
| `make lint/docs-html` | pass |
| `make lint/prose` | pass, 1 intentional demo error, no new findings |
| `make pre-commit` | pass, including `lint/go`, `lint/ts`,
`lint/shellcheck`, and a slim build |
| Manifest audit | every path resolves to a file on disk; entry-by-entry
diff shows only the expected moves |

Generated with Coder Agents on behalf of @nickvigilante.


<details>
<summary>CI note: doc-check failure is infrastructure, not this
PR</summary>

`Analyze PR for Documentation Updates Needed` fails before it reviews
anything: the Coder account behind `agents-chat-action` returns `User is
not active (status = "suspended")`. It isn't a required check.
`check-docs` (linkspector) and every other check pass on `58ed9e3e4b`.

_CI note added by Coder Agents on behalf of @nickvigilante._
</details>
2026-09-24 13:51:38 -04:00

520 lines
14 KiB
Go

package main
import (
"fmt"
"os"
"path/filepath"
"regexp"
"strings"
"time"
"golang.org/x/xerrors"
"github.com/coder/coder/v2/cli/cliui"
"github.com/coder/pretty"
"github.com/coder/serpent"
)
const (
calendarStartMarker = "<!-- RELEASE_CALENDAR_START -->"
calendarEndMarker = "<!-- RELEASE_CALENDAR_END -->"
releasesFile = "docs/reference/releases.md"
kubernetesFile = "docs/install/server/kubernetes/index.md"
rancherFile = "docs/install/server/rancher.md"
changelogURLFmt = "https://coder.com/changelog/coder-%d-%d"
releaseTagURLFmt = "https://github.com/coder/coder/releases/tag/%s"
)
// calendarRow represents one row in the release calendar table.
type calendarRow struct {
// ReleaseName is the display name, e.g. "2.30" or
// "[2.30](https://...)".
ReleaseName string
// Major and Minor parsed from the release name.
Major int
Minor int
// ReleaseDate as displayed, e.g. "February 03, 2026".
ReleaseDate string
// Status like "Mainline", "Stable", "Not Supported", etc.
Status string
// LatestRelease as displayed, e.g.
// "[v2.30.0](https://...)".
LatestRelease string
}
var autoversionPragmaRe = regexp.MustCompile(
`<!-- ?autoversion\(([^)]+)\): ?"([^"]+)" ?-->`,
)
// parseCalendarTable extracts calendar rows from the markdown
// between the start and end markers. Returns the rows and the
// column widths for re-rendering.
func parseCalendarTable(content string) ([]calendarRow, error) {
startIdx := strings.Index(content, calendarStartMarker)
endIdx := strings.Index(content, calendarEndMarker)
if startIdx == -1 || endIdx == -1 {
return nil, xerrors.New("calendar markers not found")
}
tableContent := content[startIdx+len(calendarStartMarker) : endIdx]
lines := strings.Split(strings.TrimSpace(tableContent), "\n")
var rows []calendarRow
for _, line := range lines {
line = strings.TrimSpace(line)
if line == "" {
continue
}
// Skip header and separator lines.
if strings.HasPrefix(line, "| Release") ||
strings.HasPrefix(line, "|---") ||
strings.HasPrefix(line, "|-") {
continue
}
if !strings.HasPrefix(line, "|") {
continue
}
cols := strings.Split(line, "|")
// Split on "|" gives empty first and last elements.
if len(cols) < 5 {
continue
}
name := strings.TrimSpace(cols[1])
date := strings.TrimSpace(cols[2])
status := strings.TrimSpace(cols[3])
latest := strings.TrimSpace(cols[4])
major, minor := parseReleaseName(name)
rows = append(rows, calendarRow{
ReleaseName: name,
Major: major,
Minor: minor,
ReleaseDate: date,
Status: status,
LatestRelease: latest,
})
}
if len(rows) == 0 {
return nil, xerrors.New("no calendar rows found")
}
return rows, nil
}
// parseReleaseName extracts major.minor from a release name
// like "2.30" or "[2.30](https://...)".
func parseReleaseName(name string) (major, minor int) {
// Strip markdown link if present.
re := regexp.MustCompile(`\[(\d+\.\d+)\]`)
if m := re.FindStringSubmatch(name); len(m) > 1 {
name = m[1]
}
_, _ = fmt.Sscanf(name, "%d.%d", &major, &minor)
return major, minor
}
// renderCalendarTable renders the calendar rows as a markdown
// table.
func renderCalendarTable(rows []calendarRow) string {
// Compute column widths.
nameW, dateW, statusW, latestW := 12, 12, 6, 14
for _, r := range rows {
if len(r.ReleaseName) > nameW {
nameW = len(r.ReleaseName)
}
if len(r.ReleaseDate) > dateW {
dateW = len(r.ReleaseDate)
}
if len(r.Status) > statusW {
statusW = len(r.Status)
}
if len(r.LatestRelease) > latestW {
latestW = len(r.LatestRelease)
}
}
var b strings.Builder
// Header.
_, _ = fmt.Fprintf(&b, "| %-*s | %-*s | %-*s | %-*s |\n",
nameW, "Release name",
dateW, "Release Date",
statusW, "Status",
latestW, "Latest Release")
// Separator.
_, _ = fmt.Fprintf(&b, "|%s|%s|%s|%s|\n",
strings.Repeat("-", nameW+1),
strings.Repeat("-", dateW+2),
strings.Repeat("-", statusW+2),
strings.Repeat("-", latestW+2))
// Data rows.
for _, r := range rows {
_, _ = fmt.Fprintf(&b, "| %-*s | %-*s | %-*s | %-*s |\n",
nameW, r.ReleaseName,
dateW, r.ReleaseDate,
statusW, r.Status,
latestW, r.LatestRelease)
}
return b.String()
}
// updateCalendar modifies the calendar rows based on the new
// release version and channel.
func updateCalendar(
rows []calendarRow,
newVer version,
channel string,
) []calendarRow {
// For any release, update the "Latest Release" for the
// matching major.minor row.
for i, r := range rows {
if r.Major == newVer.Major && r.Minor == newVer.Minor {
rows[i].LatestRelease = fmt.Sprintf(
"[%s](%s)",
newVer.String(),
fmt.Sprintf(releaseTagURLFmt, newVer.String()),
)
// If this row was "Not Released", update it.
if r.Status == "Not Released" {
rows[i].Status = "Mainline"
rows[i].ReleaseDate = time.Now().Format("January 02, 2006")
rows[i].ReleaseName = fmt.Sprintf(
"[%d.%d](%s)",
newVer.Major, newVer.Minor,
fmt.Sprintf(changelogURLFmt, newVer.Major, newVer.Minor),
)
}
}
}
// For patch releases, we only update Latest Release — done
// above.
if newVer.Patch > 0 {
return rows
}
// For new mainline releases (patch == 0), apply status
// transitions.
if channel == "mainline" {
for i, r := range rows {
switch {
case r.Major == newVer.Major && r.Minor == newVer.Minor:
// Already handled above.
continue
case r.Status == "Mainline":
rows[i].Status = "Stable"
case strings.Contains(r.Status, "Stable"):
// "Stable", "Stable + ESR" → Security Support.
rows[i].Status = "Security Support"
case r.Status == "Security Support":
rows[i].Status = "Not Supported"
}
}
// Add "Not Released" row for the next minor.
nextMinor := newVer.Minor + 1
hasNext := false
for _, r := range rows {
if r.Major == newVer.Major && r.Minor == nextMinor {
hasNext = true
break
}
}
if !hasNext {
rows = append(rows, calendarRow{
ReleaseName: fmt.Sprintf("%d.%d", newVer.Major, nextMinor),
Major: newVer.Major,
Minor: nextMinor,
ReleaseDate: "",
Status: "Not Released",
LatestRelease: "N/A",
})
}
// Trim oldest "Not Supported" rows to keep roughly
// the same number of rows. We allow up to the
// current count + 1 (for the new "Not Released"
// row), then trim.
rows = trimOldestNotSupported(rows)
}
return rows
}
// trimOldestNotSupported removes "Not Supported" rows from the
// start until we have at most 8 rows total, keeping at least
// one "Not Supported" row if any exist.
func trimOldestNotSupported(rows []calendarRow) []calendarRow {
const maxRows = 8
for len(rows) > maxRows {
// Find the first "Not Supported" row.
found := -1
for i, r := range rows {
if r.Status == "Not Supported" {
found = i
break
}
}
if found == -1 {
break
}
// Count how many "Not Supported" rows we have.
nsCount := 0
for _, r := range rows {
if r.Status == "Not Supported" {
nsCount++
}
}
// Keep at least one.
if nsCount <= 1 {
break
}
rows = append(rows[:found], rows[found+1:]...)
}
return rows
}
// updateCalendarFile reads the releases index.md, updates the
// calendar table, and writes it back.
func updateCalendarFile(
repoRoot string,
newVer version,
channel string,
) error {
path := filepath.Join(repoRoot, releasesFile)
content, err := os.ReadFile(path)
if err != nil {
return xerrors.Errorf("reading %s: %w", releasesFile, err)
}
rows, err := parseCalendarTable(string(content))
if err != nil {
return xerrors.Errorf("parsing calendar: %w", err)
}
rows = updateCalendar(rows, newVer, channel)
newTable := renderCalendarTable(rows)
// Replace the content between markers.
s := string(content)
startIdx := strings.Index(s, calendarStartMarker)
endIdx := strings.Index(s, calendarEndMarker)
updated := s[:startIdx+len(calendarStartMarker)] +
"\n" + newTable +
s[endIdx:]
//nolint:gosec // File permissions match the original.
return os.WriteFile(path, []byte(updated), 0o644)
}
// updateAutoversionFile reads a markdown file and replaces
// version strings in lines following autoversion pragmas for
// the given channel.
func updateAutoversionFile(path, channel, newVer string) error {
content, err := os.ReadFile(path)
if err != nil {
return xerrors.Errorf("reading %s: %w", path, err)
}
lines := strings.Split(string(content), "\n")
changed := false
for i, line := range lines {
m := autoversionPragmaRe.FindStringSubmatch(line)
if len(m) < 3 {
continue
}
pragmaChannel := m[1]
pattern := m[2]
if pragmaChannel != channel {
continue
}
// Build regex from the pattern by replacing
// [version] with a capture group.
escaped := regexp.QuoteMeta(pattern)
reStr := strings.ReplaceAll(
escaped,
regexp.QuoteMeta("[version]"),
`(\d+\.\d+\.\d+)`,
)
re, err := regexp.Compile(reStr)
if err != nil {
continue
}
// Search the next few lines for a match.
for j := i + 1; j < len(lines) && j <= i+5; j++ {
if loc := re.FindStringSubmatchIndex(lines[j]); loc != nil {
// loc[2]:loc[3] is the version capture
// group.
lines[j] = lines[j][:loc[2]] + newVer + lines[j][loc[3]:]
changed = true
break
}
}
}
if !changed {
return nil
}
//nolint:gosec // File permissions match the original.
return os.WriteFile(path, []byte(strings.Join(lines, "\n")), 0o644)
}
// updateRancherFile updates the version strings in rancher.md.
func updateRancherFile(path, channel, newVer string) error {
content, err := os.ReadFile(path)
if err != nil {
return xerrors.Errorf("reading %s: %w", path, err)
}
s := string(content)
switch channel {
case "mainline":
// Match: - **Mainline**: `X.Y.Z`
re := regexp.MustCompile(
`(\*\*Mainline\*\*: ` + "`)" + `\d+\.\d+\.\d+` + "(`)",
)
s = re.ReplaceAllString(s, "${1}"+newVer+"${2}")
case "stable":
re := regexp.MustCompile(
`(\*\*Stable\*\*: ` + "`)" + `\d+\.\d+\.\d+` + "(`)",
)
s = re.ReplaceAllString(s, "${1}"+newVer+"${2}")
default:
return nil
}
//nolint:gosec // File permissions match the original.
return os.WriteFile(path, []byte(s), 0o644)
}
// updateReleaseDocs updates all release-related docs files and
// creates a PR with the changes.
//
//nolint:revive // dryRun flag is needed to control PR creation behavior.
func updateReleaseDocs(
inv *serpent.Invocation,
newVer version,
channel string,
dryRun bool,
) error {
w := inv.Stderr
// Find the repo root (where .git is).
repoRoot, err := gitOutput("rev-parse", "--show-toplevel")
if err != nil {
return xerrors.Errorf("finding repo root: %w", err)
}
verStr := fmt.Sprintf("%d.%d.%d", newVer.Major, newVer.Minor, newVer.Patch)
vTag := "v" + verStr
branchName := fmt.Sprintf("docs/update-release-%s", vTag)
infof(w, "Updating release docs for %s (channel: %s)...", vTag, channel)
fmt.Fprintln(w)
if dryRun {
_, _ = fmt.Fprintf(w, "[DRYRUN] would update %s\n", releasesFile)
_, _ = fmt.Fprintf(w, "[DRYRUN] would update %s\n", kubernetesFile)
_, _ = fmt.Fprintf(w, "[DRYRUN] would update %s\n", rancherFile)
_, _ = fmt.Fprintf(w, "[DRYRUN] would create branch %s\n", branchName)
_, _ = fmt.Fprintf(w, "[DRYRUN] would create PR: chore(docs): update release docs for %s\n", vTag)
return nil
}
// Create a new branch from main.
if err := gitRun("checkout", "-b", branchName, "origin/main"); err != nil {
return xerrors.Errorf("creating branch: %w", err)
}
// Update the files.
if err := updateCalendarFile(repoRoot, newVer, channel); err != nil {
return xerrors.Errorf("updating calendar: %w", err)
}
successf(w, "Updated %s", releasesFile)
k8sPath := filepath.Join(repoRoot, kubernetesFile)
if err := updateAutoversionFile(k8sPath, channel, verStr); err != nil {
return xerrors.Errorf("updating kubernetes.md: %w", err)
}
successf(w, "Updated %s", kubernetesFile)
rancherPath := filepath.Join(repoRoot, rancherFile)
if err := updateRancherFile(rancherPath, channel, verStr); err != nil {
return xerrors.Errorf("updating rancher.md: %w", err)
}
successf(w, "Updated %s", rancherFile)
// Stage and commit.
if err := gitRun("add",
filepath.Join(repoRoot, releasesFile),
k8sPath,
rancherPath,
); err != nil {
return xerrors.Errorf("staging files: %w", err)
}
commitMsg := fmt.Sprintf("chore(docs): update release docs for %s", vTag)
if err := gitRun("commit", "-m", commitMsg); err != nil {
return xerrors.Errorf("committing: %w", err)
}
// Push and create PR.
if err := gitRun("push", "origin", branchName); err != nil {
return xerrors.Errorf("pushing branch: %w", err)
}
prTitle := commitMsg
prBody := fmt.Sprintf("Automated docs update for %s release.\n\nCreated by `releasetui`.", vTag)
out, err := ghOutput("pr", "create",
"--repo", owner+"/"+repo,
"--title", prTitle,
"--body", prBody,
"--base", "main",
"--head", branchName,
)
if err != nil {
return xerrors.Errorf("creating PR: %w", err)
}
prURL := strings.TrimSpace(out)
successf(w, "Created PR: %s", prURL)
fmt.Fprintln(w)
infof(w, "Review and merge the PR to complete the docs update.")
return nil
}
// promptAndUpdateDocs asks the user if they want to create a
// docs update PR and does so if confirmed.
func promptAndUpdateDocs(
inv *serpent.Invocation,
newVer version,
channel string,
dryRun bool,
) {
w := inv.Stderr
_, _ = fmt.Fprintln(w)
_, _ = fmt.Fprintln(w, pretty.Sprint(cliui.BoldFmt(),
"Next step: create a PR updating release docs "+
"(calendar, helm versions, rancher)."))
_, _ = fmt.Fprintln(w)
if err := confirmWithDefault(inv, "Create docs update PR?", cliui.ConfirmYes); err != nil {
infof(w, "Skipped docs update. You can update them manually.")
return
}
if err := updateReleaseDocs(inv, newVer, channel, dryRun); err != nil {
warnf(w, "Failed to create docs PR: %v", err)
warnf(w, "You'll need to update release docs manually.")
}
}