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

Đang mở
#1,616 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
55/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
github-actions, json, powershell
Lĩnh vực
ci-cd, documentation

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
PowerShell
Star
218
Fork
48
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của microsoftgraph/entra-powershell

Tất cả issue của microsoftgraph/entra-powershell

Issue tương tự

Thêm issue về DevOps

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.