Commit Graph
2 Commits
Author SHA1 Message Date
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
Garrett Delfosse 76b35edaff ci: backport to ESR and ESR-1 release branches (#27460)
## What

Extend the backport workflow so the `backport` label fans out to **every
actively supported release channel**, not just the latest three minors.

Target branches are now the union of:

- the latest 3 `release/2.X` branches (mainline `n`, stable `n-1`,
security `n-2`), and
- the active **ESR** and **maintenance ESR (ESR-1)** branches.

The set is de-duplicated, so a branch that is both stable and ESR (today
`release/2.34`) is backported once. Dry-run against the current branch
list yields `release/2.29`, `release/2.33`, `release/2.34`,
`release/2.35`.

## Why

ESR / ESR-1 are designated biannually and can sit well below the top-3
window, so the previous `head -3` heuristic silently skipped them (e.g.
the maintenance ESR `release/2.29`). The current ESR was only covered by
coincidence when it happened to equal stable.

## Changes

- Add `scripts/release_channels/esr_versions.txt` as the single source
of truth for active ESR minors.
- `scripts/update-release-calendar.sh` now reads that file instead of a
hardcoded `ESR_VERSIONS` array (calendar output verified unchanged).
- `backport.yaml` `detect` job unions the latest 3 branches with the ESR
branches (existence-checked, warns and skips missing ones) and
de-duplicates.
- Backport PRs now get a `backport/v<version>` label, mirroring
`cherry-pick.yaml`, with `issues: write` added to create the label.

### Resilience to partial failures

Even with the independent matrix (`fail-fast: false`), a single branch's
job could previously abort without leaving anything behind, forcing the
remaining branches to be backported entirely by hand. Fixed so each
branch always ends with a PR (real or placeholder):

- Label, assignee, and reviewer are attached **after** the PR is
created, as best-effort steps. Requesting review from / assigning the PR
author is rejected by GitHub, which previously aborted `gh pr create`
under `set -e` and left no PR.
- Idempotency now keys off an existing backport **PR** rather than the
branch, and an existing backport branch is reused instead of bailing, so
a re-run recovers a branch that was pushed before its PR was opened.
- The workflow now comments on the original PR with each created
backport link, flagging conflicts that still need manual resolution.
- Conflicting cherry-picks continue to open a placeholder PR with
copy-paste resolution steps.

## Validation

- `actionlint`, `shellcheck -x`, and `zizmor` all pass.
- Re-ran `update-release-calendar.sh`; ESR statuses (`2.29 Extended
Support Release`, `2.34 Stable (ESR)`) are identical after the refactor.
- Dry-ran the detection logic against the live branch list (see set
above).

<details>
<summary>Implementation plan</summary>

# Plan: Backport to all supported release channels (mainline, stable,
security, ESR, ESR-1)

## Goal

The backport GitHub Action should open cherry-pick PRs against every
actively supported release branch:

| Channel | Meaning | Example today |

|-------------------------|-----------------------------|----------------|
| Mainline | last release (n) | `release/2.35` |
| Stable | n-1 | `release/2.34` |
| Security Support | n-2 | `release/2.33` |
| ESR | current Extended Support | `release/2.34` |
| Maintenance ESR (ESR-1) | previous ESR still patched | `release/2.29`
|

All channels map to `release/2.X` branches.

## What we targeted before

`.github/workflows/backport.yaml` took the exact `release/2.X` branches,
sorted by minor descending, and kept the top 3
(mainline/stable/security). ESR and ESR-1 are not derivable from version
ordering, so the maintenance ESR was silently skipped.

## Source of truth for ESR branches

`scripts/update-release-calendar.sh` already encoded the active ESR
minors (`ESR_VERSIONS=(29 34)`), driving the release calendar. Rather
than maintaining a second list, this list was extracted into a shared
data file consumed by both the calendar script and the workflow.

## Changes

1. Extract the ESR minors into
`scripts/release_channels/esr_versions.txt`; update
`update-release-calendar.sh` to read it.
2. Extend the `detect` job to emit the union of the top-3 branches and
one `release/2.<minor>` per ESR entry, existence-checked and
de-duplicated.
3. Add per-release `backport/v<version>` labels (with `issues: write`),
mirroring the cherry-pick workflow.

## Assumptions

- Major version is always `2` (matches existing code).
- The ESR list is maintained manually when ESR versions change.
- `cherry-pick.yaml` stays single-branch and is out of scope.
- Missing ESR branches are skipped with a warning, not a failure.

</details>

---
*Opened by Coder Agents on behalf of @f0ssel.*
2026-07-24 12:13:19 -04:00