Skip to content

fetch_asam_specs.py rewrites the tracked INDEX.md from a stale template, and adds an OpenSCENARIO row to it #523

Description

@JArmandoAnaya

Found while running the documented OpenSCENARIO fetch during p8-s1 PR-B (#245).

What happens

CLAUDE.md and third_party/asam/INDEX.md both tell you to fetch the OpenSCENARIO text locally with:

python scripts/fetch_asam_specs.py --std openscenario --out third_party/asam

That command works — but it also regenerates third_party/asam/INDEX.md, which is a tracked file, from a template that predates #521. Running it leaves the worktree dirty in a way that is easy to git add -A by accident, and the regenerated file is wrong in three ways:

  1. It adds a row for openscenario-xml-1.4.0/ to the "Contents" table — of the very file whose job is to record that OpenSCENARIO is not tracked. Committing that advertises the spec as part of the repo.
  2. It reverts docs: draft GW-6, and track the OpenDRIVE specification in-repo #521's curated prose: the rights/licence pointer, the "both OpenDRIVE versions are kept on purpose" paragraph, the "Not tracked" table with the fetch instructions, and the erratum-review note all disappear, replaced by an older "Licensing policy" / "Rules" pair that says redistribution is merely "unclear".
  3. The numbers disagree with the committed file: the generator writes Pages (90 / 93) where the tracked file says Chapters (20 / 20), so the two were already out of sync before this.

Why it matters

The gitignore only covers the spec bodies (third_party/asam/openscenario-*/). INDEX.md is tracked, so the one command the docs tell a P8 contributor to run is also the one that silently corrupts a tracked file — and the corruption is precisely "claim we ship a spec we must not ship".

Related trap, worth fixing in the same pass: symlinking the spec directory in from another checkout does not work either. The ignore pattern third_party/asam/openscenario-*/ has a trailing slash, so it matches a directory but not a symlink, and git reports the symlink as untracked and committable.

Suggested fix

Either teach scripts/fetch_asam_specs.py to leave INDEX.md alone unless --std all was requested (and to never list an untracked spec in the tracked contents table), or regenerate INDEX.md from the current committed text so a fetch is a no-op for it. A cheap guard on top: a CI check that third_party/asam/INDEX.md never names openscenario, other than in its "Not tracked" section.

Filed rather than fixed in #245's PR-B: it is a scripts/docs defect with its own blast radius, and PR-B is already a large kernel change.

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

    helpIn-app Help & documentation systempillar:P8Road to Parity pillar P8

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions