Skip to content

Docs: tighten numeric env-var parsing guarantee after #1991 lands #2036

Description

@steilerDev

[product-owner]

As a self-hosting operator reading the configuration reference, I want the numeric-variable caution box to state the actual guarantee once strict parsing lands, so that I am not warned about a truncation hazard that no longer exists.

Priority: Could Have
Blocked by: #1991

Problem

docs/src/getting-started/configuration.md currently tells operators that an invalid numeric value causes startup failure, qualified — per PR #2027 — with the caveat that a value beginning with digits is truncated rather than rejected (AUTH_RATE_LIMIT_MAX=2e3 silently becomes 2).

That qualification is accurate today and was written deliberately as true-of-today, not as though #1991 had already landed. Once #1991 merges, loadConfig() rejects 2e3, 20abc, 20.9, and ' 20' outright, and the caveat becomes conservative but still true — it warns about a hazard that no longer exists.

Note the ordering is safe in one direction only: the docs never lie, they just understate. There is no window in which an operator is misinformed, which is why this is a follow-up rather than a co-requisite of #1991.

Acceptance Criteria

  • 1 Given Tighten integer parsing for numeric environment variables in loadConfig() #1991 has merged, When the configuration reference describes numeric environment variables, Then the truncation caveat added by PR docs: document auth rate-limit env vars on configuration page #2027 is removed and the copy states the simpler guarantee: a malformed numeric value fails startup rather than being silently coerced.
  • 2 The copy states what "malformed" covers concretely — trailing characters, decimals, exponent notation, and surrounding whitespace — so an operator can predict the behaviour rather than infer it from one example.
  • 3 The copy does not overstate: values that are well-formed integers but out of range (e.g. a negative PORT) fail with a range error, which is a different message from a parse error. Do not collapse the two into one claim.
  • 4 No "known issue" pointer to Tighten integer parsing for numeric environment variables in loadConfig() #1991 or any tracker item is added — the copy stands on its own as a description of shipped behaviour.
  • 5 npm run docs:build passes (the release-time onBrokenAnchors: 'throw' build), verified locally rather than inferred from a green PR — docs-only PRs make the CI gates green by vacuity.

Notes

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions