Skip to content

Fix content bugs found in Terminus docs audit - #2

Draft
EdwardAngert wants to merge 1 commit into
chore/refresh-terminus-datafrom
content/terminus-audit-fixes
Draft

Fix content bugs found in Terminus docs audit#2
EdwardAngert wants to merge 1 commit into
chore/refresh-terminus-datafrom
content/terminus-audit-fixes

Conversation

@EdwardAngert

@EdwardAngert EdwardAngert commented Jul 23, 2026

Copy link
Copy Markdown
Owner

Summary

Stacked on #1 (data refresh) and pantheon-systems#10177 (automation mechanism). Concrete, verified issues from a full-set audit of src/source/content/terminus, cross-checked against a clone of pantheon-systems/terminus where the finding depended on real command/config behavior.

  • 07-create.md: invalid composer.json in two examples (backslash instead of forward slash in a package name; missing comma between extra and require-dev blocks), a namespace mismatch between the documented distribution namespace and the composer.json autoload examples, a mismatched code-fence length that would break rendering, a mislabeled .gitignore code block, and stale example values (PHP 7.0.11, Terminus ^1.1/^3 compatible-version constraints against a current major of 4.x).
  • 09-configuration.md: clarifies that hide_git_mode_warning (config.yml) and TERMINUS_HIDE_GIT_MODE_WARNING (env var) are the same switch — confirmed via TerminusConfig's TERMINUS_<KEY> env-var mapping in the Terminus source, which the doc never explained.
  • 05-scripting.md: clarifies TERMINUS_SITE is a real Terminus-recognized env var (confirmed in src/Hooks/SiteEnvLookup.php, fires on every command with a site/site_env argument), unlike the self-defined ORG_UUID/PANTHEON_ORG examples nearby.
  • 11-updates.md: fixed a self-referential link (pointed at its own page instead of the Terminus 4.0 migration doc) and added links to both major-version migration docs, which were otherwise unreachable from the page readers actually land on.
  • 12-terminus-3-0.md: added a forward-pointer to the 4.0 migration guide now that the doc is reachable again.
  • 10-supported-terminus.md: fixed a heading hierarchy skip (body text straight to an H3 with no H2 in between).
  • 06-plugins.md: added missing cross-references to the plugin directory and create-a-plugin docs.
  • ci/circleci.md: fixed an instruction telling readers to find-and-replace a literal TOKEN string that doesn't exist in the script; the other three CI docs already describe this correctly as a CircleCI env var.
  • ci/bitbucket.md, ci/github-actions.md, ci/gitlab.md: fixed a repeated "how to to authenticate" typo.
  • 03-examples.md: fixed two internal anchor links pointing at headings that don't exist on the page.
  • 01-introduction.md: removed an unnecessary "powerful tool" flourish.

Intentionally out of scope: the CircleCI 1.0 test-automation example in 07-create.md is stale as a whole (CircleCI 1.0 is long deprecated) and needs a fuller rewrite, not a targeted fix; the placeholder site-name inconsistency in 03-examples.md and its duplicated "Basic Format" block with 04-commands.md are consolidation calls better suited to a follow-up pass.

This PR targets the fork for the same stacking reason as #1; re-target or reopen against upstream once the branches below it land there.

Reviewer action needed: reviewed frontmatter

src/source/data/schema.yaml defines reviewed as "the date this file was last reviewed by a member of the docs team" — a human-provenance claim, not a generic last-touched timestamp. This PR fixes real content in 03-examples.md, ci/circleci.md, ci/bitbucket.md, and ci/gitlab.md (all of which already carry a reviewed date, now stale relative to these fixes), and in 05-scripting.md, 06-plugins.md, 07-create.md, 09-configuration.md, 10-supported-terminus.md, 11-updates.md, and 12-terminus-3-0.md (none of which have the field at all). I deliberately did not set or update reviewed on any of them — that's not mine to attest to. Whoever reviews this PR should update reviewed to today's date on the files they've actually reviewed as part of merging it.

Test plan

  • Extracted every JSON code block from 07-create.md programmatically and validated with json.loads (not hand-checked) — all 3 valid
  • Grepped all TerminusHello* occurrences to confirm namespace consistency across the file
  • Confirmed heading anchors (#basic-format, #apply-updates, #login-via-machine-token-required) exist and match the site's actual rehype-slug slugging behavior
  • Confirmed all internal permalinks referenced (/terminus/create, /terminus/directory, /terminus/terminus-4-0, /terminus/terminus-3-0) against target files' frontmatter
  • Re-verified TERMINUS_SITE/hide_git_mode_warning claims directly against Terminus source (SiteEnvLookup.php, TerminusConfig.php, SSHBaseCommand.php)
  • Repo-wide grep confirms zero remaining "how to to" typos
  • Reviewer updates reviewed frontmatter on files they've reviewed (see above)

Built with docs-agent-plugin

🤖 Generated with Claude Code

Concrete, verified issues from a full-set audit of src/source/content/terminus,
cross-checked against a clone of pantheon-systems/terminus where the finding
depended on real command/config behavior:

- 07-create.md: invalid composer.json in two examples (backslash instead of
  forward slash in a package name; missing comma between "extra" and
  "require-dev" blocks), a namespace mismatch between the documented
  distribution namespace and the composer.json autoload examples, a
  mismatched code-fence length that would break rendering, a mislabeled
  .gitignore code block, and stale example values (PHP 7.0.11, Terminus
  ^1.1/^3 compatible-version constraints against a current major of 4.x).
- 09-configuration.md: clarifies that `hide_git_mode_warning` (config.yml)
  and `TERMINUS_HIDE_GIT_MODE_WARNING` (env var) are the same switch --
  confirmed via TerminusConfig's TERMINUS_<KEY> env-var mapping in the
  Terminus source, which the doc never explained.
- 05-scripting.md: clarifies TERMINUS_SITE is a real Terminus-recognized
  env var (confirmed in src/Hooks/SiteEnvLookup.php), unlike the
  self-defined ORG_UUID/PANTHEON_ORG examples nearby.
- 11-updates.md: fixed a self-referential link (pointed at its own page
  instead of the Terminus 4.0 migration doc) and added links to both
  major-version migration docs, which were otherwise unreachable from the
  page readers actually land on.
- 12-terminus-3-0.md: added a forward-pointer to the 4.0 migration guide
  now that the doc is reachable again.
- 10-supported-terminus.md: fixed a heading hierarchy skip (body text
  straight to an H3 with no H2 in between).
- 06-plugins.md: added missing cross-references to the plugin directory
  and create-a-plugin docs.
- ci/circleci.md: fixed an instruction telling readers to find-and-replace
  a literal `TOKEN` string that doesn't exist in the script; the other
  three CI docs already describe this correctly as a CircleCI env var.
- ci/bitbucket.md, ci/github-actions.md, ci/gitlab.md: fixed a repeated
  "how to to authenticate" typo.
- 03-examples.md: fixed two internal anchor links pointing at headings
  that don't exist on the page.
- 01-introduction.md: removed an unnecessary "powerful tool" flourish.

Items intentionally left out of scope: the CircleCI 1.0 test-automation
example in 07-create.md is stale as a whole (CircleCI 1.0 is long
deprecated) and would need a fuller rewrite, not a targeted fix; the
placeholder site-name inconsistency in 03-examples.md and its duplicated
"Basic Format" block with 04-commands.md are consolidation calls better
suited to a follow-up pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant