Fix content bugs found in Terminus docs audit - #2
Draft
EdwardAngert wants to merge 1 commit into
Draft
Conversation
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>
4 tasks
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
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.
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 ofpantheon-systems/terminuswhere the finding depended on real command/config behavior.composer.jsonin two examples (backslash instead of forward slash in a package name; missing comma betweenextraandrequire-devblocks), 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.gitignorecode block, and stale example values (PHP 7.0.11, Terminus^1.1/^3compatible-version constraints against a current major of 4.x).hide_git_mode_warning(config.yml) andTERMINUS_HIDE_GIT_MODE_WARNING(env var) are the same switch — confirmed viaTerminusConfig'sTERMINUS_<KEY>env-var mapping in the Terminus source, which the doc never explained.TERMINUS_SITEis a real Terminus-recognized env var (confirmed insrc/Hooks/SiteEnvLookup.php, fires on every command with asite/site_envargument), unlike the self-definedORG_UUID/PANTHEON_ORGexamples nearby.TOKENstring that doesn't exist in the script; the other three CI docs already describe this correctly as a CircleCI env var.Intentionally out of scope: the CircleCI 1.0 test-automation example in
07-create.mdis stale as a whole (CircleCI 1.0 is long deprecated) and needs a fuller rewrite, not a targeted fix; the placeholder site-name inconsistency in03-examples.mdand its duplicated "Basic Format" block with04-commands.mdare 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:
reviewedfrontmattersrc/source/data/schema.yamldefinesreviewedas "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 in03-examples.md,ci/circleci.md,ci/bitbucket.md, andci/gitlab.md(all of which already carry arevieweddate, now stale relative to these fixes), and in05-scripting.md,06-plugins.md,07-create.md,09-configuration.md,10-supported-terminus.md,11-updates.md, and12-terminus-3-0.md(none of which have the field at all). I deliberately did not set or updatereviewedon any of them — that's not mine to attest to. Whoever reviews this PR should updatereviewedto today's date on the files they've actually reviewed as part of merging it.Test plan
07-create.mdprogrammatically and validated withjson.loads(not hand-checked) — all 3 validTerminusHello*occurrences to confirm namespace consistency across the file#basic-format,#apply-updates,#login-via-machine-token-required) exist and match the site's actualrehype-slugslugging behavior/terminus/create,/terminus/directory,/terminus/terminus-4-0,/terminus/terminus-3-0) against target files' frontmatterTERMINUS_SITE/hide_git_mode_warningclaims directly against Terminus source (SiteEnvLookup.php,TerminusConfig.php,SSHBaseCommand.php)reviewedfrontmatter on files they've reviewed (see above)Built with docs-agent-plugin
🤖 Generated with Claude Code