Skip to content

[bv] Retire env-var-as-option fallback in OptionsService #263

@rdeago

Description

@rdeago

Reference version

2.0.103-preview.

Background and motivation

OptionsService reads option values via a fallback:

  1. Explicit values set via SetOption (called from SettingsApplier after Spectre parses [CommandOption]s).
  2. Environment variables, with names derived from option keys via a camelCase→UPPER_SNAKE regex pipeline in OptionNameToEnvironmentVariableName.

Step 2 is a holdover from the Cake-script era of these workflows, where setting env vars was the natural way to parameterize the build. With bv, CLI args are first-class and just as ergonomic in CI. The fallback now carries cost without offsetting benefit:

  • The regex pipeline is non-trivial (three passes) and the mapping is undocumented at the option-definition site: from [CommandOption("--main-branch <NAME>")] in BuildSettings.cs, you can't see that MAIN_BRANCH is also accepted. (The two affected [Description] strings spell it out for --configuration and --main-branch only — partial coverage.)
  • Renaming an option silently breaks any consumer relying on the env-var form. PR [bv] English help output and kebab-case-only release options #261 illustrates: UPDATE_SELF_REFERENCES, documented in CHANGELOG.md as a public surface for 1.1.4, became DOGFOOD with no warning path for users with the old env var still set.
  • The companion bug ([ci] release.yml has three silently-ignored workflow_dispatch inputs #262) shows misnamed env vars produce no error, just silently-ignored inputs — a property of the lookup being silent.

Proposed enhancement

Drop the env-var lookup path from OptionsService.TryGetOptionString. The service becomes a thin key → value map populated only by SetOption. CI workflows pass values via CLI args; nothing else needs to change.

Implementation proposals

  • Remove the env-var-lookup branch in OptionsService.TryGetOptionString.
  • Remove OptionNameToEnvironmentVariableName and its three [GeneratedRegex] partials.
  • Adjust GetOptionOrFail's error message to drop the env-var equivalent reference.
  • Trim the [Description] text for Configuration and MainBranch in BuildSettings.cs to remove the "or the X environment variable" parenthetical.
  • CHANGELOG.md documents the removal as a **BREAKING CHANGE**.

Usage examples

Before, in CI:

env:
  MAIN_BRANCH: 'main'
  CONFIGURATION: 'Release'
steps:
- run: dotnet bv build

After:

steps:
- run: dotnet bv build --main-branch main --configuration Release

Risks

Breaking change for any user relying on env-var defaults in CI. Acceptable scope: bv is in preview, the public env-var surface is already partially broken by the renames in #261, and the migration is a one-line shell change per option.

Additional information

Acceptance criteria

  • OptionsService reads only from explicitly-set options (no env-var fallback).
  • BuildSettings.cs descriptions no longer mention env-var fallbacks.
  • CHANGELOG.md entry under **BREAKING CHANGE**.
  • dotnet bv pack succeeds with zero errors and zero warnings.
  • dotnet dnx JetBrains.ReSharper.GlobalTools inspectcode --severity=WARNING … reports zero results.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancement[issue/PR] requests / implements new or improved functionality.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions