Skip to content

feat(env): warn at runtime on deprecated forms#886

Merged
Chemaclass merged 1 commit into
mainfrom
feat/deprecation-warnings
Jul 25, 2026
Merged

feat(env): warn at runtime on deprecated forms#886
Chemaclass merged 1 commit into
mainfrom
feat/deprecation-warnings

Conversation

@Chemaclass

Copy link
Copy Markdown
Member

🤔 Background

Related #866

Deprecations were recorded only in help text and docs, with no path out. The unprefixed
settings have been superseded since 0.15.0 (~23 months) and bashunit test --assert since
the assert subcommand landed — neither ever told a user at runtime, which is how a
deprecation stays in place indefinitely.

This adds the mechanism and the policy, without removing anything.

💡 Changes

  • bashunit::env::warn_deprecated, wired to the unprefixed settings and --assert. Output goes to stderr so it cannot corrupt a report on stdout; BASHUNIT_NO_DEPRECATION_WARNINGS=true silences it
  • Detection runs before the := block — afterwards the prefixed name is set either way and the two cases are indistinguishable — and is pure bash, since a compgen -v capture would cost a fork on the budgeted cold-start path
  • The hand-maintained alias list is kept honest by an anti-drift test against env.sh, matching the approach already used for the shell completions
  • Documents the policy: a deprecated form warns for at least one minor release before removal in a major one

⚠️ Worth knowing

-a/--assert is not a pure rename. It goes through cmd_test's parser, so it also
accepts --env and --no-parallel; bashunit assert forwards everything to the
assertion instead. I found this by migrating tests to the new form and watching them
fail. That gap has to close before the old form can actually be removed — recorded in the
code rather than left to be rediscovered.

Deprecations were recorded only in help text and docs, with no path out:
the unprefixed aliases have been superseded since 0.15.0 and 'bashunit
test --assert' since the assert subcommand landed, and neither ever told
a user at runtime.

Adds bashunit::env::warn_deprecated and wires it to both. The warning
goes to stderr so it cannot corrupt a report on stdout, and
BASHUNIT_NO_DEPRECATION_WARNINGS=true silences it.

Detection for the unprefixed aliases runs before the ':=' block, because
afterwards the prefixed name is set either way and the two cases are
indistinguishable. It is pure bash: a 'compgen -v' capture would cost a
fork on the budgeted cold-start path. The hand-maintained alias list is
kept honest by an anti-drift test against env.sh.

Documents the policy: a deprecated form warns for at least one minor
before removal in a major.

Note '-a/--assert' is NOT a pure rename -- it goes through cmd_test's
parser so it also accepts --env/--no-parallel, which 'bashunit assert'
forwards to the assertion instead. That gap must close before the form
can be removed; recorded in the code.
@Chemaclass Chemaclass added the enhancement New feature or request label Jul 25, 2026
@Chemaclass Chemaclass self-assigned this Jul 25, 2026
@Chemaclass
Chemaclass merged commit a72ba72 into main Jul 25, 2026
37 of 39 checks passed
@Chemaclass
Chemaclass deleted the feat/deprecation-warnings branch July 25, 2026 13:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant