Repository navigation
release: v1.6.1 - bug-report filtering, DocFX API reference, Pages deploy - #3
Merged
Merged
Conversation
The Bug Report API held 383 CHDSharpCli reports and every one of them was a
chdman-parity input validation, not a defect: 382x "Data size ... is not
divisible by sector size 2048" and 1x "createdvd requires --input ...".
Those paths already printed the right text and returned exit code 1, but they
logged at Warning, and BugReportSink forwards every Warning+ event.
- BugReportSink now skips events tagged with the UserError property.
- Add ILogger.UserError(...) (CHDSharpCli/UserErrorLogging.cs): warning level
for the console and rolling file logs, tagged so no report is sent.
- Tag the 216 usage/validation warnings in the CLI (bad flags, invalid
numbers, missing paths, sector-misaligned input, existing output without
--force, overridden format options, ...). Console text and exit codes are
unchanged, so chdman parity is untouched.
- Real runtime failures (Open failed, * failed: {Message}, verify failures,
TOC extraction failures) stay on Warning and are still reported.
- Regression tests for the two reported paths.
- Document the convention in AGENTS.md and docs/logging.md.
The out-parameter overloads combined <inheritdoc cref=...> with explicit <param> tags for parameters the inherited comment already documents, so DocFX reported 14 "Duplicate parameter" warnings while generating metadata. Keep <inheritdoc> for the parameters that are identical and document only the extra out parameters (chdVersion/chdSha1/chdMd5). ReadHeader(Stream,...) had no inherited parameters in common, so it now documents itself fully. docfx metadata: 0 warnings.
The guides had a hand-written API page but no per-member reference. - DocFX 2.81.0 is pinned in .config/dotnet-tools.json; docfx.json generates the managed reference for CHDSharpLib (net10.0) into docfx/ and renders the site to _site/api. - scripts/build-api-docs.ps1 runs metadata + build + the theme step, so local and CI output are identical. - .github/workflows/pages.yml builds the Jekyll guides and the API reference into one artifact and deploys it with actions/deploy-pages. GitHub Pages moves to build_type: workflow, so the wiki job no longer requests a legacy rebuild (ci.yml, release.yml). - The CI docs job now also builds DocFX, so broken XML docs fail the gate. - docs/_config.yml pins baseurl: /CHDSharp: Jekyll is no longer run by the Pages builder, which used to inject the project prefix. - The sidebar and the hand-written API page link to /api/, and the reference uses the same GitHub-dark palette as the guides. - Generated metadata (docfx/*.yml) and the rendered _site/ are git-ignored.
Bug-fix and documentation release. - Expected user/usage errors no longer reach the Bug Report API (v1.6.0 behavior change is already in main's fix commit). - DocFX API reference published with the docs site. - Version 1.6.1 in Directory.Build.props; WhatsNew.md, docs/ReleaseNotes.md, README.md, CHDSharpLib/README.md, per-project banners and PackageReleaseNotes updated; docs/building.md version examples refreshed.
…rloads Replacing the duplicate <param> tags with <inheritdoc cref=...> removed the DocFX warnings but introduced CS1573: Roslyn does not expand inheritdoc when deciding whether a partially documented method is complete, and CHDSharpLib turns that warning into an error for pack/build with -warnaserror. Drop <inheritdoc> on the three out-parameter overloads and document every parameter (and a summary) explicitly, so both DocFX and the compiler are clean. ReadHeader(Stream,...) already documents its two parameters.
The four vendored ports must stay verbatim for byte-for-byte chdman parity, so inspecting them only invites "fixes" that would break the guarantee. Skip VendoredFlac, VendoredLZMA, VendoredZLib and VendoredZSTD wholesale (projects and sources) with --exclude="Vendored*/**" instead of only their .cs files, and spell the rule out in AGENTS.md and docs/building.md.
…isabled GitHub returns 404 from the dependency-graph API for this repository and does not expose a way to enable the graph for user-owned repositories, so the review action could only ever fail with "not supported on this repository". Probe the SBOM endpoint first: when the graph is unavailable, emit a warning annotation and skip the review so the check reflects reality. Enabling the graph in Settings > Code security and analysis restores enforcement with no workflow change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CHDSharpClireports and all were normal validation outcomes (382Data size ... is not divisible by sector size 2048, 1createdvd requires --input ...). They already matchedchdman(same text, exit code 1); they were just logged at Warning and the sink forwards Warning+. AddedILogger.UserError(...)which tags the event soBugReportSinkskips it while the console/file logs stay unchanged. 216 usage/validation call sites reclassified; genuine runtime failures still report. Verified live: both paths now produce 0 reports.scripts/build-api-docs.ps1, newpages.ymldeploying Jekyll guides +/api/viaactions/deploy-pages,baseurlmade explicit, CI docs job now builds both.<param>blocks so DocFX metadata is warning-free.Verification
dotnet test: 14,019/14,019 passed (net8/9/10).dotnet build -c Release -warnaserror: 0 warnings, 0 errors.jb inspectcode --severity=WARNING: 0 findings.docfx metadata/build: 0 warnings.