From 77cd61111d7fe47c865701bf6f2a25e37fb8d2ec Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Thu, 23 Jul 2026 13:29:13 -0400 Subject: [PATCH] Fix content bugs found in Terminus docs audit 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_ 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 --- .../content/terminus/01-introduction.md | 2 +- src/source/content/terminus/03-examples.md | 4 ++-- src/source/content/terminus/05-scripting.md | 4 ++-- src/source/content/terminus/06-plugins.md | 2 ++ src/source/content/terminus/07-create.md | 20 +++++++++---------- .../content/terminus/09-configuration.md | 4 ++-- .../content/terminus/10-supported-terminus.md | 2 ++ src/source/content/terminus/11-updates.md | 3 ++- .../content/terminus/12-terminus-3-0.md | 2 +- src/source/content/terminus/ci/bitbucket.md | 2 +- src/source/content/terminus/ci/circleci.md | 3 +-- .../content/terminus/ci/github-actions.md | 2 +- src/source/content/terminus/ci/gitlab.md | 2 +- 13 files changed, 28 insertions(+), 24 deletions(-) diff --git a/src/source/content/terminus/01-introduction.md b/src/source/content/terminus/01-introduction.md index 6f33a4773a..1888a848ce 100644 --- a/src/source/content/terminus/01-introduction.md +++ b/src/source/content/terminus/01-introduction.md @@ -22,7 +22,7 @@ Terminus is a command line interface that provides advanced interaction with Pan ## Terminus Features -Terminus is a powerful tool that allows you to: +Terminus allows you to: - Create a new site - Create and delete Multidev environments diff --git a/src/source/content/terminus/03-examples.md b/src/source/content/terminus/03-examples.md index 935a179d42..05cabec5f9 100644 --- a/src/source/content/terminus/03-examples.md +++ b/src/source/content/terminus/03-examples.md @@ -84,7 +84,7 @@ The example above is equivalent to `terminus env:info mysite.dev`. Pantheon supports [Drush (Drupal)](https://drushcommands.com/) and [WP-CLI (WordPress)](https://developer.wordpress.org/cli/commands/) commands remotely against a target site environment through Terminus. This is often faster and easier than leveraging such tools via local installations. -1. Use the [basic command structure described above](#command-structure). +1. Use the [basic command structure described above](#basic-format). The commands to invoke Drush and WP-CLI are: - `remote:drush` @@ -431,7 +431,7 @@ Every site has an assigned upstream to deliver [one-click updates](/core-updates -1. Apply updates to the site to bring in the new codebase after setting the upstream. Refer to the [example usage above](#applying-updates) for information on how to apply updates. +1. Apply updates to the site to bring in the new codebase after setting the upstream. Refer to the [example usage above](#apply-updates) for information on how to apply updates. ## Troubleshoot Upstreams diff --git a/src/source/content/terminus/05-scripting.md b/src/source/content/terminus/05-scripting.md index b319df9470..de53d3a4f0 100644 --- a/src/source/content/terminus/05-scripting.md +++ b/src/source/content/terminus/05-scripting.md @@ -29,7 +29,7 @@ If so, consider how you can turn the task into a script. ## Authentication -Terminus must be authenticated before you can execute most commands. You must authenticate Terminus with a [machine token](/terminus/install#machine-token) that has the correct permissions before running a script. +Terminus must be authenticated before you can execute most commands. You must authenticate Terminus with a [machine token](/terminus/install#login-via-machine-token-required) that has the correct permissions before running a script. ### Authenticate Terminus for Continuous Integration @@ -70,7 +70,7 @@ Terminus can generate variables for scripting. In the example below, `terminus m PANTHEON_MULTIDEV_LIST="$(terminus multidev:list -n ${TERMINUS_SITE} --format=list --field=Name)" ``` -This example assumes the variable `TERMINUS_SITE` is already set. You can iterate through `$PANTHEON_MULTIDEV_LIST` using a `while read` loop to perform tasks on each Multidev environment. +This example assumes the variable `TERMINUS_SITE` is already set. Unlike the `ORG_UUID` and `PANTHEON_ORG` variables in the examples below, `TERMINUS_SITE` is a Terminus-recognized environment variable, so you can export it once (in your shell profile or CI environment) instead of setting it within each script. You can iterate through `$PANTHEON_MULTIDEV_LIST` using a `while read` loop to perform tasks on each Multidev environment. ## Interactive Prompts diff --git a/src/source/content/terminus/06-plugins.md b/src/source/content/terminus/06-plugins.md index b219337936..4e0b54f7ff 100644 --- a/src/source/content/terminus/06-plugins.md +++ b/src/source/content/terminus/06-plugins.md @@ -47,5 +47,7 @@ terminus self:plugin:uninstall pantheon-systems/terminus-plugin-example ## More Resources +- [Plugin Directory](/terminus/directory) +- [Create Terminus Plugins](/terminus/create) - [WordPress Plugins and Themes with Known Issues](/wordpress-known-issues) - [Drupal Modules with Known Issues](/modules-known-issues) \ No newline at end of file diff --git a/src/source/content/terminus/07-create.md b/src/source/content/terminus/07-create.md index 410f75bc9d..8548d31183 100644 --- a/src/source/content/terminus/07-create.md +++ b/src/source/content/terminus/07-create.md @@ -91,7 +91,7 @@ Some of the following instructions may break your plugin temporarily. We recomme ```json { - "name": "pantheon-systems\terminus-hello-world" + "name": "pantheon-systems/terminus-hello-world" } ``` @@ -113,11 +113,11 @@ Some of the following instructions may break your plugin temporarily. We recomme "description": "An Hello, World Terminus command", "type": "terminus-plugin", "autoload": { - "psr-4": { "Pantheon\\TerminusHello\\": "src" } + "psr-4": { "Pantheon\\TerminusHelloWorld\\": "src" } }, "extra": { "terminus": { - "compatible-version": "^3" + "compatible-version": "^4" } } } @@ -161,16 +161,16 @@ The instructions in this section demonstrate how to set up simple functional tes "description": "A Hello, World Terminus command", "type": "terminus-plugin", "autoload": { - "psr-4": { "Pantheon\\TerminusHello\\": "src" } + "psr-4": { "Pantheon\\TerminusHelloWorld\\": "src" } }, "require": { "organization/project-name": "^1" }, "extra": { "terminus": { - "compatible-version": "^1.1" + "compatible-version": "^4" } - } + }, "require-dev": { "squizlabs/php_codesniffer": "^2.7" }, @@ -208,7 +208,7 @@ The instructions in this section demonstrate how to set up simple functional tes 1. Add the following lines to the `.gitignore`file. This is **strongly** recommended because of the additional files created by these tests. - ```bash{promptUser: user} + ```text vendor bats bin @@ -218,7 +218,7 @@ The instructions in this section demonstrate how to set up simple functional tes 1. Define your Bats tests. Create a folder named `tests`, and create a file named `confirm-install.bats`. Place the content below in your Bats test file: - ``````bash{promptUser: user} + ```bash{promptUser: user} #!/usr/bin/env bats # @@ -262,7 +262,7 @@ You can [configure your project tests to run automatically on Circle CI](https:/ timezone: America/Chicago php: - version: 7.0.11 + version: 8.1 environment: PATH: $PATH:~/.composer/vendor/bin:~/.config/composer/vendor/bin:$HOME/bin @@ -273,7 +273,7 @@ You can [configure your project tests to run automatically on Circle CI](https:/ - composer install --prefer-dist -n - composer install-bats - composer global require -n "consolidation/cgr" - - cgr "pantheon-systems/terminus:^1.1" + - cgr "pantheon-systems/terminus:^4" post: - terminus auth:login --machine-token=$TERMINUS_TOKEN test: diff --git a/src/source/content/terminus/09-configuration.md b/src/source/content/terminus/09-configuration.md index f44bc1ac9f..30d4feb5f9 100644 --- a/src/source/content/terminus/09-configuration.md +++ b/src/source/content/terminus/09-configuration.md @@ -47,7 +47,7 @@ command: The example above does three things: -- Terminus warns you when running commands in an environment set to Git mode, unaware if the command affects the codebase or not. +- By default, Terminus warns you when running commands in an environment set to Git mode, unaware if the command affects the codebase or not. Set `hide_git_mode_warning: 1` to disable that warning. - The `terminus auth:login` command automatically provides the correct email address when it runs. This is useful if you find yourself logging in to multiple accounts frequently, and want to use your regular account by default. @@ -55,7 +55,7 @@ The example above does three things: [warning] This environment is in read-only Git mode. If you want to make changes to the codebase of this site (e.g. updating modules or plugins), you will need to toggle into read/write SFTP mode first. ``` - Defining `TERMINUS_HIDE_GIT_MODE_WARNING` disables that message, which is useful for those using Terminus for frequent changes to files, not code. + Set the environment variable `TERMINUS_HIDE_GIT_MODE_WARNING` for the same effect as `hide_git_mode_warning: 1` in `config.yml` — Terminus maps any `TERMINUS_` environment variable to the matching `config.yml` key automatically, so the two are interchangeable. This is useful for those using Terminus for frequent changes to files, not code. - The Terminus Plugin [Pancakes](https://github.com/terminus-plugin-project/terminus-pancakes-plugin) lets you open your Pantheon site database with a SQL GUI client. Rather than define the app every time. This configuration always uses [Sequel Ace](https://sequel-ace.com/) unless otherwise specified. diff --git a/src/source/content/terminus/10-supported-terminus.md b/src/source/content/terminus/10-supported-terminus.md index 1932e4dfef..d8e82b4323 100644 --- a/src/source/content/terminus/10-supported-terminus.md +++ b/src/source/content/terminus/10-supported-terminus.md @@ -21,6 +21,8 @@ Each major and minor version of Terminus is fully supported for one year from th After this period, the version will reach End Of Life (**EOL**), and will no longer be supported. We recommend you update Terminus far in advance of the EOL schedule, so that regressions in new versions can be reported and patched in time. +## Version Support + | Version | Release Date | EOL Date | |------------------|--------------------|--------------------| | 4.3.2 | June 23, 2026 | | diff --git a/src/source/content/terminus/11-updates.md b/src/source/content/terminus/11-updates.md index 52f74a1607..9e01e64c61 100644 --- a/src/source/content/terminus/11-updates.md +++ b/src/source/content/terminus/11-updates.md @@ -23,4 +23,5 @@ integration: [--] ## More Resources - [Terminus Command Reference](/terminus/commands) -- [Terminus 4.0](/terminus/updates) \ No newline at end of file +- [Terminus 4.0 Migration Guide](/terminus/terminus-4-0) +- [Terminus 3.0 Migration Guide](/terminus/terminus-3-0) \ No newline at end of file diff --git a/src/source/content/terminus/12-terminus-3-0.md b/src/source/content/terminus/12-terminus-3-0.md index ac039bb701..45c841a105 100644 --- a/src/source/content/terminus/12-terminus-3-0.md +++ b/src/source/content/terminus/12-terminus-3-0.md @@ -17,7 +17,7 @@ product: [terminus] integration: [--] --- -This section provides information about Terminus 3.0. Terminus 3.0 is the most recent major version of Terminus and is recommended in place of Terminus 2.0. +This section provides information about Terminus 3.0, which was recommended in place of Terminus 2.0. Terminus 3.0 is no longer the most recent major version — see the [Terminus 4.0 Migration Guide](/terminus/terminus-4-0) if you're upgrading from Terminus 2.x or earlier. diff --git a/src/source/content/terminus/ci/bitbucket.md b/src/source/content/terminus/ci/bitbucket.md index ea087b8690..827736838d 100644 --- a/src/source/content/terminus/ci/bitbucket.md +++ b/src/source/content/terminus/ci/bitbucket.md @@ -18,7 +18,7 @@ integration: [--] reviewed: "2023-06-08" --- -This section provides information on how to to authenticate Terminus in a Bitbucket CI pipeline without receiving errors and avoiding authentication rate limits. +This section provides information on how to authenticate Terminus in a Bitbucket CI pipeline without receiving errors and avoiding authentication rate limits. ## Caching Authentication for Bitbucket Pipelines diff --git a/src/source/content/terminus/ci/circleci.md b/src/source/content/terminus/ci/circleci.md index 9e429d815b..619f1fde95 100644 --- a/src/source/content/terminus/ci/circleci.md +++ b/src/source/content/terminus/ci/circleci.md @@ -41,8 +41,7 @@ You can use the example script in this section for a full start-to-finish Termin Before you use this script: -- Replace `TOKEN` in the script below with the machine token provided by Terminus. -- Add the machine token provided by Terminus to your environment variables in the CircleCI project settings. +- Add a `TERMINUS_TOKEN` environment variable in your CircleCI project settings, set to the machine token provided by Terminus. diff --git a/src/source/content/terminus/ci/github-actions.md b/src/source/content/terminus/ci/github-actions.md index 0420fac3ea..3388c05755 100644 --- a/src/source/content/terminus/ci/github-actions.md +++ b/src/source/content/terminus/ci/github-actions.md @@ -18,7 +18,7 @@ integration: [--] reviewed: "2025-12-10" --- -This section provides information on how to to authenticate Terminus in a GitHub Actions CI pipeline without receiving errors and avoiding authentication rate limits. +This section provides information on how to authenticate Terminus in a GitHub Actions CI pipeline without receiving errors and avoiding authentication rate limits. ## Caching Authentication for GitHub Actions diff --git a/src/source/content/terminus/ci/gitlab.md b/src/source/content/terminus/ci/gitlab.md index d1499798e9..afbc66342c 100644 --- a/src/source/content/terminus/ci/gitlab.md +++ b/src/source/content/terminus/ci/gitlab.md @@ -18,7 +18,7 @@ integration: [--] reviewed: "2023-06-08" --- -This section provides information on how to to authenticate Terminus in a GitLab CI pipeline without receiving errors and avoiding authentication rate limits. +This section provides information on how to authenticate Terminus in a GitLab CI pipeline without receiving errors and avoiding authentication rate limits. ## Caching Authentication for GitLab