Skip to content

forgelm/templates/LICENSES.md: false claim — Templates can rely on the trainer's default for gradient_checkpointing (auto-enabled when CUDA is available — see forgelm/trainer.py); only set it expli… (DOC-D4B02-005) #271

Open
Open
forgelm/templates/LICENSES.md: false claim — Templates can rely on the trainer's default for gradient_checkpointing (auto-enabled when CUDA is available — see forgelm/trainer.py); only set it expli… (DOC-D4B02-005)#271
Assignees
saipraneeth143
Labels
backlog: knownAlready tracked in docs/roadmapdocumentationImprovements or additions to documentationfirst-timers-onlyReserved for a contributor's very first pull requestgood first issueGood for newcomersseverity: highWrong behaviour or a false claim users rely onsource: review-2026-10Found by the October 2026 code and documentation reviewwave: 1Roadmap wave 1: high severity, small effort
Milestone
Wave 1 — public contract and documented usage

Description

@cemililik
cemililik
opened on Oct 9, 2026

Wave 1 · theme D1-10: Documentation-only fixes · highest severity High · 1 finding(s) · effort docs fix

Summary

A contributor who follows the guidance and sets gradient_checkpointing in a template config breaks forgelm quickstart for that template (config error, exit 1).

Primary finding

DOC-D4B02-005 — forgelm/templates/LICENSES.md: false claim — Templates can rely on the trainer's default for gradient_checkpointing (auto-enabled when CUDA is available — see forgelm/trainer.py); only set it expli…

severity High · already tracked: KNOWN-OPEN C31-DOC-SCHEMA-PROSE docs/roadmap/risks-and-decisions.md:184

Where. forgelm/templates/LICENSES.md:31-34 · type: false claim

The document says. Templates can rely on the trainer's default for gradient_checkpointing (auto-enabled when CUDA is available — see forgelm/trainer.py); only set it explicitly when you need to override.

What the code does. The auto-enable part is true (trainer.py:514 sets gradient_checkpointing = torch.cuda.is_available()). An override cannot be set: TrainingConfig has no gradient_checkpointing field and extra='forbid' rejects it. Verified: a config with training.gradient_checkpointing: true fails with "Extra inputs are not permitted".

Code references. forgelm/trainer.py:514, forgelm/config.py:443-613, forgelm/config.py:449

User impact. A contributor who follows the guidance and sets gradient_checkpointing in a template config breaks forgelm quickstart for that template (config error, exit 1).

Proposed correction. Templates cannot set gradient_checkpointing: it is not a config field (TrainingConfig forbids unknown keys). The trainer enables it automatically when CUDA is available (see forgelm/trainer.py).

Acceptance criteria

  • Each statement is re-checked against the code at fix time.
  • Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
  • Every finding in this issue is resolved or explicitly closed with a reason.

Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.

Activity

  1. cemililik
    added this to the v0.12.0 — Wave 1: public contract and documented usage milestone on Oct 9, 2026
  2. cemililik
    added
    documentationImprovements or additions to documentation
    backlog: knownAlready tracked in docs/roadmap
    severity: highWrong behaviour or a false claim users rely on
    source: review-2026-10Found by the October 2026 code and documentation review
    wave: 1Roadmap wave 1: high severity, small effort
    on Oct 9, 2026
  3. cemililik
    added this to ForgeLM Project Planon Oct 9, 2026
  4. cemililik
    added a parent issue on Oct 9, 2026

  5. cemililik commented on Oct 22, 2026

    @cemililik
    cemililik
    on Oct 22, 2026
    CollaboratorAuthor

    Where to start

    Thanks for taking a look. Claim it by starting a comment with /assign so nobody duplicates the work.

    What is wrong. Item 2 of "Adding a new template" in forgelm/templates/LICENSES.md (about lines 30-34) says a template can rely on the trainer's default for gradient_checkpointing and "only set it explicitly when you need to override".

    • The first half is true: the trainer turns it on when CUDA is available (forgelm/trainer.py, search for "gradient_checkpointing": torch.cuda.is_available()).
    • The second half is false: TrainingConfig has no such field and rejects unknown keys. A template that sets it fails validation, and forgelm quickstart stops with a config error. You can see it yourself:
    import yaml
from forgelm.config import ForgeConfig
d = yaml.safe_load(open("forgelm/templates/customer-support/config.yaml").read().split("---", 1)[1])
d["data"]["dataset_name_or_path"] = "forgelm/templates/customer-support/data.jsonl"
ForgeConfig(**d)                                   # loads
d["training"]["gradient_checkpointing"] = True
ForgeConfig(**d)                                   # ValidationError: Extra inputs are not permitted

    What to change. Reword item 2 so that it says:

    • templates cannot set gradient_checkpointing, because it is not a config field (TrainingConfig forbids unknown keys, so the config fails validation);
    • the trainer enables it automatically when CUDA is available (see forgelm/trainer.py).

    Keep the rest of the item (QLoRA 4-bit NF4, rank ≤ 8, safety/compliance opt-in only). The maintainers have already decided that it stays a non-field (decision C-9 of Phase 16 step S8), so there is no choice left for you to make.

    Please leave docs/guides/troubleshooting.md alone. It has a similar gradient_checkpointing: true snippet, but that is tracked separately and needs its Turkish mirror.

    python3 tools/check_source_path_refs.py --strict
pytest tests/test_quickstart.py --no-cov

    No new test is needed for a wording fix. The file is contributor-facing, so no CHANGELOG line is needed either. forgelm/templates/LICENSES.md has no Turkish mirror, so the issue's "Turkish mirror" line does not apply.

    Open the PR against development with Fixes #271 (finding DOC-D4B02-005).

  6. cemililik
    added
    good first issueGood for newcomers
    first-timers-onlyReserved for a contributor's very first pull request
    on Oct 22, 2026

  7. saipraneeth143 commented on Oct 26, 2026

    @saipraneeth143
    saipraneeth143
    on Oct 26, 2026

    Hi! I’m a first-time contributor taking part in Hacktoberfest. I’d like to work on this docs fix. I’ll check the claim against forgelm/trainer.py, correct templates/LICENSES.md, and run the doc guard scripts before opening a PR. Could you assign it to me?

  8. cemililik
    assigned
    saipraneeth143
    on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

backlog: knownAlready tracked in docs/roadmapdocumentationImprovements or additions to documentationfirst-timers-onlyReserved for a contributor's very first pull requestgood first issueGood for newcomersseverity: highWrong behaviour or a false claim users rely onsource: review-2026-10Found by the October 2026 code and documentation reviewwave: 1Roadmap wave 1: high severity, small effort

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions