Skip to content

Docs site: a page on main before its 10.x cherry-pick fails the 10.x build and stops publishing #420

Closed

Description

@CaffeinatedCoder

Problem

site/build.sh builds both lines with main's site/toc.yml. A page that lands on main before its cherry-pick to release/10.x is in that menu but missing from the 10.x checkout. DocFX reports the missing menu target as a warning, and the build treats warnings as errors.

So from the first such page on:

  • Every docs PR into main fails its Build (10.x) check.
  • The live site stops updating. The publish job needs both builds, so neither line is republished until the cherry-pick lands.

CONTRIBUTING.md#the-documentation-site tells contributors to add a new page to site/toc.yml, which is exactly the step that triggers it. The walkthrough (#418) will be the first page to do so.

Found while wiring #418 into the site, before any page had triggered it.

Change

When site/build.sh builds a checkout other than its own, it removes the menu entries whose page doesn't exist in that checkout, and logs each one. When it builds its own checkout, a missing page is still an error, so main's menu is still checked in full. CONTRIBUTING says that a page on main only shows up in the 10.x menu once it's cherry-picked.

Done when

  • With a main-only page in toc.yml, the 10.x build passes without that entry and logs it, and the 11.x build includes the page.
  • A menu entry naming a page that doesn't exist on main still fails the 11.x build.
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

    area/releaseVersioning, changelogs, release wiringbugSomething isn't workingseverity/mediumInconsistency or failure in a narrow scenario

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions