Skip to content

docs: anchor the Version line strip to the generated header - #450

Open
loonghao wants to merge 1 commit into
mainfrom
fix/anchor-version-line-strip
Open

loonghao wants to merge 1 commit into
mainfrom
fix/anchor-version-line-strip

Conversation

@loonghao

Copy link
Copy Markdown
Owner

Summary

--check ignores the Version: line so a new release tag — which changes the
stamped version — does not turn main and every pull request red until someone
regenerates. The previous implementation stripped every line starting with
Version: .

This narrows that to the header only.

Why it matters

Both generated files embed the README and the example scripts. A line inside
that embedded content that happens to begin with Version: is real content,
not the version stamp. Stripping those too meant the comparison could not see
them: a content change touching only such a line would compare equal and pass
the gate silently.

Today each file happens to contain exactly one Version: line, both in the
header, so nothing is currently hidden. The mask would open as soon as embedded
content gained such a line.

The change

The strip now applies only to the header, defined as the lines before the first
## heading, which is where the generator writes its single Version: line.
Everything from the first heading down is compared as-is.

Tests

test/test_generate_llms.py covers both directions, because either alone would
pass under a broken implementation:

  • A header-only version change still compares equal (the behaviour we need).
  • A Version: line appearing in the body now makes the comparison fail
    (the regression being fixed).
  • Only the header line is stripped; body lines are preserved.
  • Degenerate documents (no body, empty input) do not raise.

The body case drives is_current against a temporary tree, so it exercises the
path the CLI actually takes rather than only the helper.

Verified against the old implementation: it reports the body change as
not drift, confirming the gap was real and is now closed.

Validation

  • python scripts/generate_llms.py --check → up to date, exit 0.
  • With an extra release tag (version-only drift) → exit 0, unchanged.
  • With a Version: 9.9.9 in body line appended to llms.txt → exit 1.
  • ruff check photoshop test scripts and ruff format --check → clean.
  • New test file: 6 passed; pytest test_generate_llms.py test_collections.py test_imports.py → 24 passed.

Configuration, generator logic and tests only. No packaging or lockfile
changes, and the generated llms.txt / llms-full.txt are unchanged.

`--check` ignores the `Version:` line so that a new release tag, which
changes the stamped version, does not turn main and every pull request
red until someone regenerates. The previous implementation stripped every
line starting with `Version: `.

Both generated files embed the README and the example scripts, so a body
line that happens to begin that way is real content. Stripping those too
would let genuine drift through the gate unnoticed: a content change that
only touched such a line would compare equal and pass.

The strip is now limited to the header, defined as the lines before the
first `## ` heading, which is where the generator writes its single
`Version: ` line. Everything below the first heading is compared as-is.

Add test/test_generate_llms.py covering the two directions that matter:
a header-only version change still compares equal, and a `Version: ` line
appearing in the body now makes the comparison fail. The end-to-end case
drives `is_current` against a temporary tree so it exercises the same path
the CLI takes rather than only the helper.

This closes the observation raised while reviewing #449.

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant