Chore(Release): v25.4 version of the docs - #763
Merged
Conversation
Cut a version and update the selector config. Snapshots docs/ and docs-graphql/ into version-v25.4 and promotes v25.4 to the version served at the site root. The snapshot carries the Zero --security documentation from #762. Also repairs the graphql plugin's version map. The v25.3 cut added "v25.3" to graphql_versions.json but never added a matching entry to docusaurus.config.ts, so /graphql/ kept serving v25.2 as latest while v25.3 appeared in the dropdown as an older version. Both v25.3 and v25.4 now have explicit entries. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
matthewmcneely
added a commit
that referenced
this pull request
Aug 19, 2026
Makes spell checking able to run, and fixes the 36 real typos it turns up. > **This PR alone does not switch spell checking back on.** GitHub Actions is disabled repository-wide (`actions/permissions` reports `"enabled": false`), and `ci-spell-checking` is additionally marked `disabled_manually`. Both are repository settings, not files, so they need an admin to flip them. See "Before this takes effect" below, which includes a hazard worth reading first. ## The problem Three separate things were wrong, and each one alone was enough to make the check vacuous. **The path filters pointed at a directory that no longer exists.** Both workflows filtered on `./content/`, which has not existed since the Docusaurus migration. `any_changed` was therefore always `false` and every step was skipped. The runs still reported success, which is why this went unnoticed. The last real run of `ci-spell-checking` was 2025-11-05. **Actions was later disabled entirely.** The last run of any of these workflows was 2025-12-04. Nothing has run since. Repointing the paths is still not enough, because the check then fails immediately on existing content. Two further causes: **`Vale.Terms` was reading the vocabulary as a casing authority.** `.github/styles/config/vocabularies/Dgraph/accept.txt` is a spelling accept-list, but `Vale.Terms` enforces the exact casing of every entry it finds there. Because the file lists both `GraphQL` and `graphql`, and lists `Cluster` without `cluster`, the result was 1,378 error-level false positives across the corpus: | Message | Count | |---------|-------| | Use 'graphql' instead of 'GraphQL'. | 652 | | Use 'Cluster' instead of 'cluster'. | 287 | | Use 'Dgraph' instead of 'dgraph'. | 118 | | ...and 12 more patterns | 321 | **`write-good` was enabled.** Its `E-Prime` rule flags every use of "is", "are", and "be", which is unworkable for reference documentation: 25 alerts in a 3-file sample. It is a prose-style linter covering ground `documentation-style-guide.md` already covers, by a different standard. ## What changed - **`.github/workflows/ci-spell-checking.yml`** — paths repointed at the four next-content directories, `*.md` and `*.mdx`. Also pins the Vale version so a new release cannot silently change what CI accepts, moves to `actions/checkout@v4` with the history `changed-files` needs, and passes the file list through the environment rather than interpolating it into the shell. - **`.github/workflows/deployments.yml`** — deleted. It ran reviewdog `misspell`, which Vale supersedes, and its filename described a deployment it never performed. CloudFlare Pages handles deployment through its GitHub integration, not a workflow. - **`.github/.vale.ini`** — `Vale.Terms` off with a comment explaining why, `write-good` dropped, `mdx` added to the file glob. - **`accept.txt`** — 145 entries added and the file sorted, so future diffs stay readable. The additions are identifiers (`backupId`, `forceFull`, `taskId`), technical terms (`backpressure`, `linearizability`, `snapshotting`, `varints`), product names, abbreviations (`PVCs`, `SSTs`, `vCPUs`), and a few deliberate oddities in sample data: `goe` and `sourc` are stemmer-output fragments in a tokenizer example, and `Un nouvel` is French sample data in an RDF example. ## The typos it found **20 misspellings**, including `Aplha` → `Alpha` in the glossary, `transactoins` → `transactions`, `Retreive` → `Retrieve`, `prediate` → `predicate`, `forfull` → `fulfill`, `wouild` → `would`, `parctices` → `practices`, `attriubutes` → `attributes`, and `Minmizes` → `Minimizes` in two link labels. **16 duplicated words**, including `will lead the the declaration` → `to the`, `must be equal the the JWT claim` → `to the`, and `what your app needs to to` → `to do`. All are fixed in `docs/`, `docs-graphql/`, and `docs-learn/`, and backported to `version-v25.4` in both versioned trees, since those are live on the site today. Older snapshots are left as the historical record they are. ## Scope Linting covers `docs/`, `docs-graphql/`, `docs-ratel/`, and `docs-learn/` only. The `*_versioned_docs/` snapshots are frozen copies that are not edited in place, and a version cut copies the next content forward already checked, so linting them would double every alert for no benefit. It also means a release PR like #763 will not drag 227 snapshot files through the linter. ## Before this takes effect **Re-enable Actions** for the repository (Settings → Actions → General), then **re-enable the `ci-spell-checking` workflow**, which is separately marked `disabled_manually`. Both are repository settings rather than files, so neither can be changed by this PR. ### Stale bot, handled here `stale.yml` runs nightly at 01:30 UTC and had no exempt labels configured, so re-enabling Actions after this long a quiet period would have marked a backlog of still-wanted work as stale. This PR adds exempt lists: - **Issues:** `bug`, `accepted`, `RFC`, `help wanted`, `good first issue`, `investigate`, `triage:delayed`, `reviewing` - **PRs:** `accepted`, `RFC`, `reviewing`, `triage:delayed`, `cherry-pick` Dependabot PRs are deliberately left unexempt. The next bump supersedes them, so closing is the right outcome. Measured against the open backlog, every item that would currently qualify as stale is now handled: | Category | Count | Outcome | |----------|-------|---------| | Issues labelled `bug` (#700, #707, #713, #730) | 4 | Exempt | | Contribution PRs (#755, #728, #708, #699) | 4 | Labelled `reviewing`, now exempt | | Dependabot PRs | 12 | Marked stale, as intended | The four contribution PRs carried no labels, so no exempt list could reach them. They have been labelled `reviewing` separately from this PR. ## Testing Since CI cannot run yet, this was verified locally with Vale 3.7.1, the version the workflow now pins: - All four content directories: **0 errors, 0 warnings, and 0 suggestions in 293 files**, exit code 0. - The CI invocation simulated against this PR's own 30 changed files: also clean, exit code 0. - `npm run build` passes, confirming the two corrected link labels still resolve. The workflow YAML parses, but it has not executed. That is the one thing here I could not verify end to end. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cuts the v25.4 documentation version and promotes it to the version served at the site root, matching the v25.4.0 release (2026-07-30).
Summary
docs/intodocs_versioned_docs/version-v25.4/anddocs-graphql/intographql_versioned_docs/version-v25.4/, viadocs:version:docsanddocs:version:graphql.lastVersion: 'v25.4'on both content plugins, with v25.4 at path''and v25.3 moved tov25.3.--securitydocumentation merged in docs: document Zero --security token and whitelist flags #762, the one user-facing change in v25.4.0.Also in here: a graphql version-map repair
Worth a look, since it is easy to miss in a 227-file diff. The v25.3 cut (b75fd1a) added
"v25.3"tographql_versions.jsonbut never added a matching entry to the graphql plugin'sversionsmap indocusaurus.config.ts. Docusaurus fell back to defaults for it, so/graphql/kept serving v25.2 (latest) while v25.3 sat above it in the dropdown as an older version. Both v25.3 and v25.4 now have explicit entries, and the GraphQL section moves from v25.2 to v25.4 as latest.URL movement
Normal for any cut, but the GraphQL section advances two versions at once:
/<page>/v25.3/<page>/graphql/<page>/graphql/v25.2/<page>/graphql/v25.3/<page>Testing
npm run buildpasses. WithonBrokenLinks: 'throw', a clean build is the link check across all five versions. Verified against the generated output inbuild/:/and/graphql/both render v25.4 (latest), with v25.3, v25.2, v25.1, and v24.1 in the dropdown./cli/zeroand/admin/security/admin-endpoint-securityinclude the--securitycontent;/v25.3/equivalents do not, since the flag is in no v25.3.x binary.Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.