Rewrite Maven site documentation on Sentry skin 8.0.00 (#113) - #125
Conversation
Replace the single-page site (skin 6.4.01, legacy SITE 1.x descriptor) with a
curated, multi-page documentation site on the latest Sentry Maven Skin.
Site tooling:
- Pin maven-site-plugin 4.0.0-M16 + maven-skin-tools 1.8.00. This fixes the
project-info-reports LinkageError (oss-parent pins site plugin 3.12.1, too old
for the Doxia 2.0 report plugins).
- Migrate src/site/site.xml to the SITE 2.0 schema and skin 8.0.00, with the
<custom> knobs (noDefaultLinks, keywords, GitHub social, additionalLinks),
grouped menus (Getting Started / Usage / Reference / reports), and top-bar
Releases + Issue Tracker links.
- Reporting: add maven-surefire-report-plugin; disable the inherited
maven-changelog-plugin (3.0.0-M1 predates Doxia 2.0). project-info, jxr,
checkstyle, pmd, spotbugs, javadoc reports are inherited from oss-parent.
Documentation pages (src/site/markdown/): index, installation, wql, commands,
authentication, tls, timeouts-and-errors, migrating-from-1x — each with
keywords/description front-matter and a MACRO{toc}, plus GitHub-flavored
[!WARNING] alerts and [!TABS] blocks.
Theming: keep the MetricsHub Poppins/blue site.css; set --content-font-size to
15px. Bump project.build.outputTimestamp to 2026 so the site copyright year and
"Documentation as of" date are current (they derive from the reproducible-build
timestamp).
Docs cleanup:
- README.md: drop the stale "WS-Man Client / winrm4j" credit (2.0.0 is a
from-scratch dependency-free client).
- README.md, CHANGELOG.md, migrating-from-1x.md: remove mentions of the
never-public org.metricshub.winrm.backend system property (tracked by #121).
GitHub Pages publishing is unchanged: the release workflow already deploys
target/site via the shared metricshub/workflows maven-central-release.yml.
Verified with `mvn clean verify site` (JDK 17): green, no LinkageError.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
bertysentry
added
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 836f2a989f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @@ -0,0 +1,111 @@ | |||
| keywords: authentication, ntlm, kerberos, spnego, domain, realm, kdc, krb5, ticket cache | |||
There was a problem hiding this comment.
All seven newly added Markdown pages start directly with metadata and omit the required license header. Add the project header to each new file, using mvn license:update-file-header as prescribed, so the repository's license checks and file policy are satisfied.
AGENTS.md reference: AGENTS.md:L7-L7
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Not making this change. The license-maven-plugin (inherited from the oss-parent POM) is configured to process only main/java/**/*.java, so mvn verify's check-file-header passes and mvn license:update-file-header does not touch Markdown. The pre-existing index.md and the sibling Jawk site follow the same no-header convention: a header would have to sit above the Doxia metadata block (keywords: / description:), which must be the first content of the file, and would break it. Happy to revisit if you'd prefer a dedicated header policy for site pages.
🤖 Addressed by Claude Code
There was a problem hiding this comment.
Follow-up: I verified this empirically. Prepending an Apache-2.0 license header (as an HTML comment) above the front-matter and rebuilding the site breaks the page — Doxia only recognizes keywords:/description: as metadata when they are the very first content, so with a header prepended the page's <meta> tags disappear and the license text plus the raw keywords:/description: lines render as visible body text. Combined with the license-maven-plugin being scoped to main/java/**/*.java (it doesn't process Markdown, and mvn verify is green) and the sibling Jawk site following the same no-header convention, I'm keeping these site pages header-free. Happy to reconsider if you'd like a different policy (e.g. a footer comment).
🤖 Addressed by Claude Code
- migrating-from-1x.md / README.md / CHANGELOG.md: stop claiming the whole public API is unchanged. A few CXF/SMB-only public types (WinRMService, SmbTempShare, KerberosCredentialsException, WindowsRemoteProcessUtils.copyLocalFilesToShare) were removed, so code that referenced them will not compile. Qualify the claim to the documented entry points and rename the migration section to "Removed types", noting the compile break. - timeouts-and-errors.md: the timeout is not a single whole-operation budget. In WinRMCommandExecutor.execute without files to copy, executeCommand() receives the full timeout after code-page detection already consumed part of it, so chained slow steps can exceed one timeout. Document the actual per-step behavior instead. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 participant
Closes #113.
Replaces the single-page Maven site (skin
6.4.01, legacy SITE 1.x descriptor) with a curated, multi-page documentation site on the latest Sentry Maven Skin8.0.00, and fixes theproject-info-reportsLinkageErrorthat the old inherited site plugin produced.Site tooling
maven-site-plugin 4.0.0-M16+maven-skin-tools 1.8.00— bumps the site plugin off the3.12.1inherited fromoss-parent(too old for the Doxia 2.0 report plugins), which is what caused thevoid org.apache.maven.doxia.sink.Sink.verbatim()LinkageError.src/site/site.xmlmigrated to the SITE 2.0 schema and skin8.0.00:<custom>knobs (noDefaultLinks, keywords, GitHubsocial,additionalLinks), grouped menus (Getting Started / Usage / Reference / reports), and top-bar Releases + Issue Tracker links.maven-surefire-report-plugin; disabled the inheritedmaven-changelog-plugin(its3.0.0-M1predates Doxia 2.0).project-info,jxr,checkstyle,pmd,spotbugs, andjavadocreports are inherited fromoss-parentand now render under the new site plugin.Documentation pages (
src/site/markdown/)Eight curated pages, each with
keywords/descriptionfront-matter and aMACRO{toc}, written from the actual public API, using GitHub-flavored[!WARNING]alerts and[!TABS]blocks:index·installation·wql·commands·authentication·tls·timeouts-and-errors·migrating-from-1xTheming
site.css; set--content-font-sizeto 15px (wasmedium= 16px).project.build.outputTimestampto a 2026 date so the site copyright year (now 2023–2026) and the "Documentation as of" date are current — these derive from the reproducible-build timestamp, so the skin can't infer them automatically while reproducibility is pinned.Docs cleanup
README.md: removed the stale "WS-Man Client / winrm4j" credit — 2.0.0 is a from-scratch, dependency-free client.README.md,CHANGELOG.md,migrating-from-1x.md: removed mentions of the never-publicorg.metricshub.winrm.backendsystem property (code removal tracked in Remove the never-public org.metricshub.winrm.backend system property from the code #121).GitHub Pages
No workflow change needed: the release workflow already deploys
target/siteto GitHub Pages via the sharedmetricshub/workflowsmaven-central-release.yml@v6(configure-pages+upload-pages-artifact+deploy-pages), served at https://metricshub.org/winrm-java.Verification
mvn clean verify siteon JDK 17 — green, noLinkageError, all 82 tests pass. Generated site confirmed: skin8.0.00, all pages + reports (project-info, Javadoc, JXR, surefire/failsafe, checkstyle/PMD/SpotBugs), resolved${project.*}interpolation, rendered TOC/tabs/alerts.Follow-ups filed
While reviewing the quality reports for this site, I filed #121 (remove the never-public backend property from the code) and #122 / #123 / #124 (fix the PMD / CPD / SpotBugs findings — currently report-only, not gating the build).
🤖 Generated with Claude Code