Skip to content

platformType: docs say it's required with no default, but a missing value still builds as web-only #1073

Open

Description

@ChronosSF

Task type

  • Other: contributor docs and tooling disagree

Description

The contributor docs and skills say every xplat topic must declare platformType, that it has no default, and that a page without it does not build. The generator does the opposite: a missing platformType is read as web-only, and the build passes.

What the code does

  • platformType() in docs/xplat/scripts/lib/api-terms.mjs returns 'web-only' when the field is missing. Its comment says this is temporary:

    Temporarily, a page that does not state it is web-only. The web-only pages carry no platformType while the JSON snippets work merges, so they stay identical to the web documentation and their owners have no edits from it to review. Restore the error below once that has landed.

  • docs/xplat/scripts/check-doc-scope.mjs (line 82) applies the same default, so the snippet-checks workflow reports 0 errors for these pages.

The JSON snippets work landed in #497 on 2026-10-20, but the error was never restored.

What the docs say (all on vnext)

  • AGENTS.md:74
  • .agents/README.md:46
  • docs/xplat/API-TERMS.md:17
  • .github/skills/xplat-docs-api-links/SKILL.md:16: "a missing or unknown value stops the build"
  • .github/skills/xplat-docs-json-snippets/SKILL.md:13 and :127: "a page without it does not build"
  • .agents/skills/igniteui-doc-topics/references/house-style.md:64 and :68, create-workflow.md:28, and audit-rubric.md:135, which rates a missing platformType as a D0 blocker

Scale

  • en: 160 of the 319 pages under docs/xplat/src/content/en/components have no platformType; 42 of them are grids/_shared/ templates. Only 2 pages declare web-only explicitly, so almost every web-only page relies on the default.
  • jp: 160 of 302.

Why it matters

  • New topics can leave out platformType and pass CI. The rewritten combo topics in feat(combo-templates): update combo templates topics #1040 are a current example.
  • The audit rubric rates a missing value as a blocker on pages CI accepts, and agents following the skills report build failures that don't happen.

Options

  1. Finish what the code comment describes. Add platformType to the pages that lack it (web-only for almost all), then restore the error in platformType() and make check-doc-scope.mjs report a missing value. The JP pages are synced by the gh-aw workflows, so decide whether they get the field in the same change or through the sync.
  2. Keep the default. Update the docs listed above to say a missing platformType means web-only, and drop "Temporarily" from the two code comments.

Acceptance criteria

  • The docs and the code agree on what a missing platformType does.
  • With option 1: every page under docs/xplat/src/content/{en,jp}/components declares platformType, and a page without it fails generate and the check-doc-scope.mjs step in snippet-checks.
  • With option 2: none of the files listed above says the field is required or that the build stops without it.

Related resources

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions