sneak/lora.vegas
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

Hugo deprecation warning: config key languageCode should become locale #18

New Issue
Closed
opened 2026-08-09 03:51:06 +02:00 by clawbot · 3 comments
clawbot commented 2026-08-09 03:51:06 +02:00
Collaborator
Copy Link
Copy Source

Problem

Building the site with a current Hugo emits:

WARN  deprecated: project config key languageCode was deprecated in
Hugo v0.158.0 and will be removed in a future release. Use locale
instead.

hugo.toml sets languageCode. Hugo deprecated that key in v0.158.0 in
favour of locale, and says it will be removed in a future release. When it
is removed the key becomes silently inert (or the build fails, depending on
how Hugo lands the removal), so this is a latent breakage, not just noise.

Found while working on #7 (PR #17); not fixed there because it is outside
that issue's scope.

Why it is not visible in CI today

The Dockerfile installs hugo from alpine 3.21's apk repo, which is hugo
0.139.0 — older than 0.158.0, so it does not emit the warning. The warning
appears on any newer hugo (seen on 0.164.0). So CI is currently green on a
Hugo old enough not to know about the deprecation, while a developer with a
current Hugo sees the warning locally. That divergence is worth noting on its
own, but is not this issue.

Definition of done

  1. hugo.toml uses locale instead of languageCode.
  2. The site builds clean on a current Hugo with no deprecation warning from
    this key.
  3. Rendered output is unchanged (the lang attribute in the emitted HTML and
    any language-derived formatting stay the same).
  4. make check passes and script/cibuild succeeds.

Out of scope

  • Bumping the Hugo version used by the Dockerfile/CI. That is a separate
    decision with its own risk and should be its own issue if wanted.
  • Any other hugo.toml restructuring.
  • The unrelated taxonomy layout warning, which is already #13.
## Problem Building the site with a current Hugo emits: WARN deprecated: project config key languageCode was deprecated in Hugo v0.158.0 and will be removed in a future release. Use locale instead. `hugo.toml` sets `languageCode`. Hugo deprecated that key in v0.158.0 in favour of `locale`, and says it will be removed in a future release. When it is removed the key becomes silently inert (or the build fails, depending on how Hugo lands the removal), so this is a latent breakage, not just noise. Found while working on #7 (PR #17); not fixed there because it is outside that issue's scope. ## Why it is not visible in CI today The `Dockerfile` installs hugo from alpine 3.21's apk repo, which is hugo 0.139.0 — older than 0.158.0, so it does not emit the warning. The warning appears on any newer hugo (seen on 0.164.0). So CI is currently green on a Hugo old enough not to know about the deprecation, while a developer with a current Hugo sees the warning locally. That divergence is worth noting on its own, but is not this issue. ## Definition of done 1. `hugo.toml` uses `locale` instead of `languageCode`. 2. The site builds clean on a current Hugo with no deprecation warning from this key. 3. Rendered output is unchanged (the `lang` attribute in the emitted HTML and any language-derived formatting stay the same). 4. `make check` passes and `script/cibuild` succeeds. ## Out of scope - Bumping the Hugo version used by the `Dockerfile`/CI. That is a separate decision with its own risk and should be its own issue if wanted. - Any other `hugo.toml` restructuring. - The unrelated taxonomy layout warning, which is already #13.
clawbot commented 2026-08-09 16:17:55 +02:00
Author
Collaborator
Copy Link
Copy Source

Sequencing update — this issue is now coupled to #26 (install Hugo at a
deliberate, hash-verified version rather than taking alpine's).

The reason this warning is invisible in CI is stated in the body above: alpine
3.21 serves Hugo 0.139.0, which predates the 0.158.0 deprecation. #26 moves the
build onto a current Hugo, which will surface this warning in CI for the
first time.

So the options are: fix this issue first, or fix it inside #26's branch. What
must not happen is #26 merging and leaving CI newly noisy — that would add a
third routinely-ignored warning alongside #13's taxonomy warning, which is
precisely the "everyone learns to ignore build output" failure mode #13 already
warns about.

Note also that this issue's definition of done says "the site builds clean on a
current Hugo with no deprecation warning from this key". Until #26 lands, that
cannot be verified in CI at all — only locally against a developer's own Hugo.
Whoever picks this up before #26 should say plainly that the verification was
local-only, rather than implying CI confirmed it. Verifying against an
environment that structurally cannot show the problem is the mistake that cost
this repo an outage in #7.

Both this and #13 are prerequisites for #25 (--panicOnWarning), which cannot
land while any warning is outstanding.

Sequencing update — this issue is now coupled to **#26** (install Hugo at a deliberate, hash-verified version rather than taking alpine's). The reason this warning is invisible in CI is stated in the body above: alpine 3.21 serves Hugo 0.139.0, which predates the 0.158.0 deprecation. #26 moves the build onto a current Hugo, which will **surface this warning in CI** for the first time. So the options are: fix this issue first, or fix it inside #26's branch. What must not happen is #26 merging and leaving CI newly noisy — that would add a third routinely-ignored warning alongside #13's taxonomy warning, which is precisely the "everyone learns to ignore build output" failure mode #13 already warns about. Note also that this issue's definition of done says "the site builds clean on a current Hugo with no deprecation warning from this key". Until #26 lands, that cannot be verified in CI at all — only locally against a developer's own Hugo. Whoever picks this up before #26 should say plainly that the verification was local-only, rather than implying CI confirmed it. Verifying against an environment that structurally cannot show the problem is the mistake that cost this repo an outage in #7. Both this and #13 are prerequisites for #25 (`--panicOnWarning`), which cannot land while any warning is outstanding.
clawbot commented 2026-08-09 16:24:31 +02:00
Author
Collaborator
Copy Link
Copy Source

Correction to my previous comment: this must NOT land before #26. Tested
rather than assumed, and the result inverts the advice.

Under CI's Hugo 0.139.0, swapping languageCode = 'en-us' for
locale = 'en-us' silently changes the generated RSS from
<language>en-us</language> to <language>en</language>. Old Hugo does not
know the locale key, ignores it, and falls back to a default. No warning, no
error, exit 0 — an output regression that the gate would not catch.

So: fix this inside #26's branch, after the Hugo version moves. Landing it
first would break output on the Hugo CI actually runs.

Added to the definition of done: the RSS <language> element must still read
en-us after the change, verified on the Hugo version the build actually uses.

**Correction to my previous comment: this must NOT land before #26.** Tested rather than assumed, and the result inverts the advice. Under CI's Hugo 0.139.0, swapping `languageCode = 'en-us'` for `locale = 'en-us'` silently changes the generated RSS from `<language>en-us</language>` to `<language>en</language>`. Old Hugo does not know the `locale` key, ignores it, and falls back to a default. No warning, no error, exit 0 — an output regression that the gate would not catch. So: **fix this inside #26's branch, after the Hugo version moves.** Landing it first would break output on the Hugo CI actually runs. Added to the definition of done: the RSS `<language>` element must still read `en-us` after the change, verified on the Hugo version the build actually uses.
clawbot commented 2026-08-09 16:29:23 +02:00
Author
Collaborator
Copy Link
Copy Source

Implementation plan

Per the correction above, this is being done inside #26's branch, in a
commit on top of the Hugo version move — not before it.

  1. Commit 1 (#26) moves the build to a deliberate, hash-verified
    hugo v0.164.0 installed by go install.
  2. Commit 2 (this issue) changes hugo.toml's languageCode = 'en-us' to
    locale = 'en-us', on top of 1, so the key is never interpreted by a Hugo
    that does not know it.

Verification, on the Hugo the build actually uses

  • RSS <language> element asserted to still read en-us — this is the
    regression the second comment above found under 0.139.0, and the whole
    reason for the ordering.
  • lang attribute in the emitted HTML unchanged.
  • public/ diffed between commit 1 and commit 2: the config change must be a
    no-op on rendered output.
  • No deprecation warning for this key in the build output.
  • Because #26 is in the same branch, this will be verified in CI and on a real
    act_runner run of deploy.yml's build job, not local-only.
## Implementation plan Per the correction above, this is being done **inside #26's branch, in a commit on top of the Hugo version move** — not before it. 1. Commit 1 (#26) moves the build to a deliberate, hash-verified **hugo v0.164.0** installed by `go install`. 2. Commit 2 (this issue) changes `hugo.toml`'s `languageCode = 'en-us'` to `locale = 'en-us'`, on top of 1, so the key is never interpreted by a Hugo that does not know it. ### Verification, on the Hugo the build actually uses - RSS `<language>` element asserted to still read `en-us` — this is the regression the second comment above found under 0.139.0, and the whole reason for the ordering. - `lang` attribute in the emitted HTML unchanged. - `public/` diffed between commit 1 and commit 2: the config change must be a no-op on rendered output. - No deprecation warning for this key in the build output. - Because #26 is in the same branch, this will be verified in CI and on a real `act_runner` run of `deploy.yml`'s `build` job, not local-only.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bot
Agent's turn to work
 merge-ready
Review passed; ready to merge
 needs-checks
PR awaiting green checks
 needs-rebase
PR needs rebase onto main
 needs-review
PR awaiting adversarial review
 needs-rework
Review failed; PR needs rework
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/lora.vegas#18