Split the Security and Threat Model pages - #83
Merged
Conversation
The page opened with the stock Commons security boilerplate and closed with a vulnerability list and a deserialization pointer, all of which the Security page already carries. Repeated on a page whose whole job is the model, they dilute it for a reader and feed irrelevant context to an agent consuming it. Drop the three repeated sections and the "Threat Model" wrapper heading, and promote what is left one level: the nine sections become top-level, and the bold pseudo-headings inside "Assumptions about the environment" become real subsections. "Reserved Settings (must not be loosened)" loses the parenthetical from its title, which would otherwise land in the anchor, and carries it in the opening sentence instead. Point the intra-page links at the anchors Doxia actually emits. They used GitHub slugs (#what-is-in-scope) where the rendered page has What_is_in_Scope, so all 23 were dead on the site. The subsections are addressable now, so the references that read "see **Supported runtimes** under [Assumptions about the environment]" become direct links. Retarget the "Supported runtimes" link that pointed at index.html, which has no such section, to the Javadoc overview section that does. Assisted-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XVaEa2R2sHtBgJh8Mhv841
Every hand-written page on this site is Markdown; the security page was the last hand-written xdoc, the other xdocs being commons-build-plugin output. Doxia derives heading ids the same way for both formats, so the section titles carry the anchors over unchanged. Add the supported release line while converting: it was stated only in the repository's SECURITY.md and nowhere on the site. Assisted-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XVaEa2R2sHtBgJh8Mhv841
The Javadoc overview renders as apidocs/index.html, so its relative links to the threat model and to the Maven coordinates resolved inside apidocs/ and 404ed; they need to climb one level. The coordinates sentence also carried a leftover Markdown link after the working anchor. The site descriptor still named the project Apache Commons Text, which the skin printed in every page title. Assisted-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XVaEa2R2sHtBgJh8Mhv841
The bullets under "What is out of scope" and "Settings you may modify" were subsections in disguise: several run seven to twelve lines with their own paragraphs and nested lists, held together only by list indentation, and nothing outside could link to one. Promote all fourteen to headings. The bullet with no bold lead-in becomes "Non-conforming JAXP implementations", matching the disposition the triage table already names, and "Android, on any API level" loses its comma, which would otherwise land in the anchor. Lift "Reserved settings" and "Settings you may modify" out of "Assumptions about the environment" first, so their cases sit at the same level as the out-of-scope ones. Neither is an assumption about the environment: supported runtimes, honored JAXP contracts, XInclude resolution and system properties are, while those two state the contract with the caller. Doxia derives ids from heading text, so both keep the anchors they had. With every case addressable, the last two-hop references collapse, and the triage table points at the specific case a disposition maps to instead of at the whole section. Assisted-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XVaEa2R2sHtBgJh8Mhv841
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
2 participants
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.
The threat model page opened with the stock Commons security boilerplate and closed with a vulnerability list and a deserialization pointer, all of which the Security page already carried. On a page whose whole job is the model, the repetition dilutes it for a reader and feeds irrelevant context to an agent consuming it.
Threat Modelwrapper heading are gone, and everything moved up a level. The bold pseudo-headings became real subsections, and so did the fourteen cases under "What is out of scope" and "Settings you may modify" — several ran seven to twelve lines with their own paragraphs and nested lists. "Reserved settings" and "Settings you may modify" moved out of "Assumptions about the environment", which now holds only what is genuinely environmental.SECURITY.md, is now on the site too.#what-is-in-scope) where the rendered page hasWhat_is_in_Scope, so all 23 were dead. The Javadoc overview's links to the threat model and to the Maven coordinates resolved insideapidocs/and 404ed. The site descriptor still named the project Apache Commons Text, which the skin printed in every page title.Verified with
mvn clean site: 83 project links across the five pages resolve, in-page anchors and relative links alike;security.htmlkeeps its four anchors and gainsSupported_Versions;threat_model.htmlcarries 30, all reachable.Reviewing: compare with whitespace ignored — Files changed → the gear icon → Hide whitespace, or append
?w=1to the URL. Promoting the list items required de-indenting their bodies out of list continuation and rewrapping them in semantic line breaks, which otherwise shows up as a rewrite of prose that did not change.🤖 Generated with Claude Code