OpenPublishing.Build fails on every PR: monikerMapping.json packageRoot is missing the docs/ prefix

Abierto
#1,616 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
55/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
github-actions, json, powershell

Línea de trabajo

Read .openpublishing.publish.config.json and module/mapping/monikerMapping.json, then verify the referenced paths against the contents of module/docs/. Check both preview monikers and confirm the expected path fields with a maintainer who can run the OpenPublishing validation build. Done means the build passes for a PR, including one that does not change documentation.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

ToTriage

Every open pull request in this repository currently shows OpenPublishing.Build as failed with the same validation error, including ones that touch no documentation at all:

[Error: PSMD2Yaml_FileLoadFailed] Failed to load file: <...>/module/mapping/monikerMapping.json.
PackageRoot, ReferenceTocUrl, and ConceptualTocUrl are required for every moniker.
PackageRoot should be a valid relative path to docset root.

Confirmed red on #1601, #1572, #1529 and #1611 (and #1611 reproduced it on two different commits, which rules out the branch contents).

Root cause

All three required keys are in fact present in module/mapping/monikerMapping.json, so the first sentence of the error is a red herring. The operative part is the second one: packageRoot is not a valid relative path to the docset root.

.openpublishing.publish.config.json sets "build_source_folder": "module", so the docset root is module/. The mapping declares:

"entra-powershell-preview": {
  "packageRoot": "entra-powershell-v1.0",
  "conceptualToc": "docs/entra-powershell-v1.0/toc.yml",
  ...
}

module/entra-powershell-v1.0 does not exist. The contents of module/ are breadcrumb, docfx.json, docs, Entra, EntraBeta and mapping. The reference markdown actually lives in module/docs/entra-powershell-v1.0/ (Applications/, Authentication/, Enable-EntraAzureADAlias.md, ...), which relative to the docset root is docs/entra-powershell-v1.0.

The inconsistency is visible inside the same JSON object: conceptualToc carries the docs/ prefix and packageRoot does not. The same mismatch exists for entra-powershell-beta-preview.

Why it started

module/mapping/monikerMapping.json has not been modified since bfeb177 (2024-03-12, "Update structure"). The module/docs/entra-powershell-v1.0 path has existed since at least 846f29c (2024-09-29). The mapping was written against the earlier layout and was not updated when the docs moved under module/docs/.

Suggested fix

Adding the prefix to both monikers would make the paths resolve:

"entra-powershell-preview":      { "packageRoot": "docs/entra-powershell-v1.0", ... }
"entra-powershell-beta-preview": { "packageRoot": "docs/entra-powershell-beta", ... }

I am deliberately filing this as an issue rather than a pull request: OpenPublishing runs inside Microsoft infrastructure, so I cannot execute the docs build to confirm the fix, and getting the docset layout wrong would affect published documentation. Someone who can trigger a validation build is better placed to confirm whether the prefix is the whole story or whether referenceTocUrl and conceptualTocUrl need adjusting alongside it.

Happy to open the PR if a maintainer confirms the direction.

Impact

While this is red, OpenPublishing.Build is not a usable signal on any PR: contributors cannot tell a real documentation regression from the pre-existing failure, and PRs that are otherwise ready carry a red check. #1611 is approved and blocked behind exactly this noise.

Lenguaje dominante
PowerShell
Estrellas
218
Forks
48
Métricas de merge de PR
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de microsoftgraph/entra-powershell

Todos los issues de microsoftgraph/entra-powershell

Issues similares

Más issues de DevOps

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.