mirror of
https://github.com/coder/coder.git
synced 2026-11-23 04:09:07 +08:00
feea5ab959f59cd2135443ed2a0c19bf7643db8f
2
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
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> |
||
|
|
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.* |