Rename inconsistent consumer-facing environment variables and script names in 2.x #2953

Summary

A full convergence pass over the codebase (PR #2952) catalogued a set of consumer-facing naming inconsistencies across VORTEX_* / DRUPAL_* environment variables and the shipped tooling script filenames. They were deliberately not renamed in that PR: every one of these names is a public contract that consumers set in their own .env and hosting configuration, or invoke as vendor/bin/vortex-*. Renaming them on main would break downstream projects silently - no error, just a setting that stops taking effect.

They belong in 2.x, where a deprecation-alias cycle can land: accept the new name, keep the old one working with a deprecation notice, then drop the old name in a later major.

Details

1. Missing TASK_ infix

VORTEX_PURGE_CACHE_ACQUIA_SKIP drops the TASK_ infix that its nine sibling variables and both other task hooks carry. Every other task-family variable reads VORTEX_TASK_<OPERATION>_<PLATFORM>_*.

2. LAGOONCLI vs CLI for the same binary

vortex-deploy-lagoon and vortex-task-custom-lagoon use different tokens for the same Lagoon CLI binary - one spells it LAGOONCLI, the other CLI.

3. Toggle polarity split three ways

Feature toggles are spelled _ENABLED (opt-in), _DISABLED (opt-out) and _SKIP (opt-out) across the codebase. A consumer cannot infer the polarity of a new toggle from its name.

4. Notification destination and credential naming

The destination variable is named three ways for the same concept:

Credentials split similarly between _TOKEN (Diffy, GitHub, JIRA) and _USER_KEY (New Relic).

5. Asymmetric admin block/unblock variables

VORTEX_LOGIN_UNBLOCK_ADMIN and VORTEX_LOGOUT_BLOCK_ADMIN encode the same underlying choice from opposite directions, where a single generic fallback would serve both.

6. VORTEX_FETCH_DB_FORCE vs VORTEX_FETCH_DB_FRESH

These two names are near-identical but have genuinely different semantics:

• VORTEX_FETCH_DB_FORCE - skip reuse of the local cached copy.
• VORTEX_FETCH_DB_FRESH - trigger a new backup or dump on the remote.

This is the highest-risk pair in the list: a consumer reaching for the wrong one gets a silently different outcome, and on Acquia or Lagoon the wrong choice triggers a remote backup that costs real time. Needs either a rename or an explicit documentation callout contrasting them side by side.

7. DRUPAL_ vs VORTEX_ prefix, and temp-path naming

Provision-subscript knobs use a DRUPAL_ prefix while everything else uses VORTEX_. Separately, DRUPAL_TMP_PATH sits outside the DRUPAL_*_FILES naming family it belongs to.

8. Tooling script filename grammar

The 42 scripts under .vortex/tooling/src/ mix grammars: verb-first (vortex-fetch-db, vortex-deploy), noun diagnostics (vortex-doctor, vortex-info), and family-suffix forms (vortex-task-copy-db-acquia). All 42 are vendor/bin/vortex-* entry points, so any rename also affects Composer bin configuration, documentation and CI.

Suggested approach

1. Decide the canonical form for each family above.
2. Land the new names in 2.x with the old names accepted as deprecated aliases, emitting a notice when the old name is the one actually set.
3. Update documentation and the installer's generated .env to the new names.
4. Drop the aliases in the following major.

Item 6 can be addressed independently and sooner, since clarifying documentation carries no breaking change.

References

• PR Converged naming, structure, API conventions and source comments across the codebase. #2952 - the convergence run that catalogued these and deliberately left them unrenamed.