Documentation cleanup across the org: plan and tracking

[slachiewicz]

Our documentation has drifted since the move off Codehaus, and in a few places it now tells people things that are no longer true. I audited the READMEs, the GitHub org surface and the generated sites, and I'd like to fix it in a small number of coordinated passes rather than ad-hoc.

This issue is the umbrella. Every PR in this effort will link back here so reviewers have the context, and I'll log settings changes as comments below.

What I found

Everything here was checked against the live API, the sources and live HTTP responses — not from memory.

Org surface

• profile/README.md in this repo is still GitHub's placeholder template ("Hi there 👋", followed by the commented-out starter prompts). It's the first thing anyone sees at github.com/codehaus-plexus.
• No SECURITY.md anywhere in the org, although plexus-archiver has 5 published advisories. There's no documented private reporting channel.
• No CONTRIBUTING.md and no issue/PR templates in any repo. Community-health scores run 12–37%.
• 12 of 19 active repos have no GitHub description, including plexus-archiver, plexus-io, plexus-interpolation, plexus-sec-dispatcher, plexus-pom and modello.
• 14 of 18 Pages sites don't have "Enforce HTTPS" on. (plexus-xml, plexus-languages, plexus-testing and plexus-build-api already do — those are the model.)

READMEs

• None of the 17 READMEs shows how to depend on the artifact. Exactly one states a Java baseline, which is awkward given plexus-sec-dispatcher and plexus-xml 4.x need Java 17 while the parent still defaults to 8.
• Nine still end with "The current master is now at https://github.com/codehaus-plexus/<that same repo>" — a 2015 redirect notice shown to people already on the page.
• plexus-interactivity has a travis-ci.org badge that renders build | unknown; plexus-archiver still opens with an "Important Hint" about a patch shipped in 3.6.0.
• Six READMEs document site publishing, with four mutually inconsistent commands. plexus-utils and plexus-xml tell you to run site site:stage scm-publish:publish-scm, but their POMs bind publish-scm to site-deploy and carry the comment "mono-module doesn't require site:stage". plexus-sec-dispatcher documents a publish command but has no scm-publish configuration at all — that one is a build bug, and I'll file it separately.

Sites

• Two links on the landing page 404: ./faq.html, and writing-components-trail/index.html — the latter is in site.xml's menu, so it's broken on every page of the site.
• "Community → Mailing Lists" points at groups.google.com/g/mojohaus-dev, which is a different organisation.
• ref/available-components.xml advertises seven components that no longer exist (plexus-cli, plexus-spring, plexus-contextualizer, plexus-xwork-integration, plexus-mail-sender, plexus-cache, plexus-swizzle) and lists none of the current ones. The overview page omits plexus-sec-dispatcher, plexus-testing and plexus-build-api, and still lists the archived plexus-digest.
• get-involved.html asks contributors to paste a "Copyright 2007 The Codehaus Foundation" header and to download maven-idea-codestyle.xml into ~/.IntelliJIDEA/config/codestyles. Formatting is enforced by Spotless with palantirJavaFormat; the real instruction is one command.
• plexus-i18n and plexus-interactivity have no POM <description>, so their generated homepage inherits the parent's: "The Plexus project provides a full software stack for creating and executing software projects." Our own landing page contradicts that — it correctly says the container was replaced by Eclipse Sisu.
• Site publishing is entirely manual; there's no site workflow in any repo. Last-published dates span May 2023 to June 2026.

What I propose

1 — Org-inherited files (this repo). Real profile README. A deliberately minimal SECURITY.md (point at GitHub private vulnerability reporting; no supported-versions table and no response-time promise, since those are commitments nobody has made). A CONTRIBUTING.md covering build, Java baseline, mvn spotless:apply, and where to ask. One light bug template and a short PR template. Plus a RELEASING.md so the publish procedure is written down once instead of six times, inconsistently.

2 — The landing site. Fix the dead links and the mailing-list pointer. Rewrite the overview into a real component index and retire available-components. Collapse the retired IoC documentation into one clearly-labelled section with a banner explaining that Eclipse Sisu replaced it. No page will be moved or deleted and no URL will change — that content is deep-linked from fifteen years of blog posts and Stack Overflow answers, and it stays exactly where it is.

3 — READMEs, one PR per repo. A common skeleton: what it is, status and version guidance, Maven coordinates, Java baseline, links to javadoc.io and the site. The status section matters most — "which plexus-utils major do I want, and what moved to plexus-xml in 4.x" is the question we get asked and answer nowhere. The skeleton is a floor, not a ceiling: repo-specific knowledge stays. plexus-classworlds' COMPATIBILITY.md is the standard I'm aiming at, not something to normalise away.

4 — Publishing. A shared, manually-dispatched site-publishing workflow, so there's one button instead of four different shell incantations. Deliberately not auto-publishing on release: that would put unreviewed content live and take the release manager out of the loop, and Maven site builds break often enough that I don't want them firing unattended.

Deliberately not doing

• No code of conduct. A CoC needs an enforcement contact and a body empowered to act on it. We have neither, and a Contributor Covenant pointing at a dead address is worse than none. Happy to be argued out of this.
• No license-header sweep. The Codehaus Foundation headers are real provenance on other people's contributions, and Modello is MIT while the rest is Apache-2.0. Nothing in this effort rewrites a copyright line.
• No content for the four empty component sites (i18n, interactivity, resources, sec-dispatcher). The README is the surface people actually reach; filling in Maven sites nobody visits isn't worth it.
• No site.xml unification or topic renaming. Bikeshed.

Settings changes

Some of this isn't PR-able — repo descriptions, "Enforce HTTPS", private vulnerability reporting. I'll apply those and log the exact commands in a comment here so they're auditable and easy to revert.

I don't have admin on plexus-xml, plexus-languages, plexus-testing, plexus-build-api or this repo, so anything needing admin there will need another maintainer.

Timing

I'll open the first PRs now so there's something concrete to react to, but I'll leave anything structural — the site menu, the README skeleton — open for at least 72 hours before merging. Straightforward corrections like the dead links I'll merge once they're green.

Please do comment, particularly on the code-of-conduct call and on the status/version-guidance wording. Those are the two parts with real judgement in them rather than just tidying.

[slachiewicz]

Settings changes applied

Logging these here as promised, since they aren't reviewable as a diff. All are reversible; the commands to undo are the same ones with the value flipped.

Repo descriptions (9 repos)

These had no description at all, so they showed blank in GitHub search, in the org repo list, and on the profile cards. Wording matches the tables in #59, and was written against the source rather than copied from the POMs — several POMs have no <description> either, which is a separate fix.

gh api -X PATCH repos/codehaus-plexus/plexus-archiver      -f description="One API over zip, jar, tar and their compressed variants"
gh api -X PATCH repos/codehaus-plexus/plexus-io            -f description="File and resource abstractions, selectors and mappers"
gh api -X PATCH repos/codehaus-plexus/plexus-interpolation -f description="Resolves \${...} expressions, the engine behind Maven POM interpolation"
gh api -X PATCH repos/codehaus-plexus/plexus-pom           -f description="The parent POM inherited by every Codehaus Plexus project"
gh api -X PATCH repos/codehaus-plexus/plexus-resources     -f description="Reads a resource from the filesystem, the classpath or a URL"
gh api -X PATCH repos/codehaus-plexus/plexus-interactivity -f description="Prompts the user on the console"
gh api -X PATCH repos/codehaus-plexus/plexus-i18n          -f description="Resource bundle lookup for localised messages"
gh api -X PATCH repos/codehaus-plexus/plexus-sec-dispatcher -f description="Encrypts and decrypts passwords in Maven settings.xml"
gh api -X PATCH repos/codehaus-plexus/modello              -f description="Generates Java classes, readers/writers, XSD and documentation from a single model file"

If any of these reads wrong to the person who knows the component best, just change it — I won't be offended.

Homepage URLs

plexus-i18n and plexus-interactivity had http:// homepage URLs. Now https://.

gh api -X PATCH repos/codehaus-plexus/plexus-i18n         -f homepage="https://codehaus-plexus.github.io/plexus-i18n/"
gh api -X PATCH repos/codehaus-plexus/plexus-interactivity -f homepage="https://codehaus-plexus.github.io/plexus-interactivity/"

Private vulnerability reporting (14 repos)

Enabled, because it is what the SECURITY.md in #60 tells people to use. It only routes reports privately to maintainers; it changes nothing else.

gh api -X PUT repos/codehaus-plexus/<repo>/private-vulnerability-reporting

Applied to: plexus-utils, plexus-archiver, plexus-compiler, plexus-io, plexus-interpolation, plexus-classworlds, plexus-pom, plexus-velocity, plexus-resources, plexus-i18n, plexus-interactivity, plexus-sec-dispatcher, modello, codehaus-plexus.github.io.

"Enforce HTTPS" — attempted, blocked

I was going to turn this on for the 14 sites that don't have it, but the API refuses:

$ gh api -X PUT repos/codehaus-plexus/plexus-utils/pages -F https_enforced=true
{"message":"The certificate does not exist yet", "status":"404"}

Worth correcting my own framing in the issue above: this is less serious than I made it sound. The sites do serve fine over HTTPS —

$ curl -sI https://codehaus-plexus.github.io/plexus-utils/   # 200

— they just don't redirect http to https. So there's no broken or unavailable TLS, only a missing redirect.

plexus-xml, plexus-languages, plexus-testing and plexus-build-api do have it enabled, and their Pages configuration is otherwise byte-identical (same legacy build type, same gh-pages source, no CNAME), so this looks like GitHub-side certificate provisioning rather than anything in our configuration. It may become settable after a Pages rebuild. I'd rather leave it than churn Pages settings on 14 repos chasing it.

Needs someone else

I don't have admin on these, so I couldn't touch them:

Repo	What's outstanding
plexus-languages	no description
plexus-build-api	no description
.github	no description
plexus-xml, plexus-languages, plexus-testing, plexus-build-api	private vulnerability reporting still off

The private-reporting one matters a little, since SECURITY.md will tell people to use a button that isn't enabled on those four. If an org owner can flip them, that closes it.

Not done, deliberately

Topic normalisation. Four repos have no topics and one has only hacktoberfest, but renaming topics across the org is bikeshed with no real payoff, so I've left it alone.

[slachiewicz]

Open for review

Eight PRs. Nothing is merged; the structural ones can sit for the 72 hours.

Org-wide files — codehaus-plexus/.github

• Replace the placeholder org profile README with a real overview #59 — profile README. Replaces the placeholder template.
• Add SECURITY, CONTRIBUTING, RELEASING and issue/PR templates #60 — SECURITY, CONTRIBUTING, RELEASING, issue/PR templates. The one I'd most like an ack on, because SECURITY.md commits other maintainers, and because it deliberately omits a code of conduct.

Site — codehaus-plexus.github.io, stacked, review in order

• Fix two broken links and the wrong mailing list codehaus-plexus.github.io#17 — two broken links + the MojoHaus mailing-list pointer. Seven lines, all deletions.
• Rewrite the overview as the component index, retire available-components codehaus-plexus.github.io#18 — overview becomes the component index; available-components retired to a pointer.
• Point contributors at CONTRIBUTING; label the retired container docs codehaus-plexus.github.io#19 — Get Involved rewritten; retired container docs relabelled.

README skeleton — pilots

• Rewrite README with usage, status and version guidance plexus-archiver#438 — busiest artifact
• Rewrite README with usage, status and version guidance plexus-i18n#37 — quiet artifact

Two pilots on purpose: a skeleton that only works for busy repos is the wrong skeleton. The remaining 15 are not open and won't be until these two are reviewed — opening 17 at once means the first review comment costs 17 force-pushes.

Parent POM

• Describe the parent POM as what it is plexus-pom#437 — replaces the inherited "full software stack" description.

Settings changes are in the comment above.

Corrections to what I wrote in this issue

Two things I got wrong, both in the direction of overstating:

HTTPS. I listed "14 of 18 Pages sites don't enforce HTTPS" among the findings. The sites do serve over HTTPS fine — they just don't redirect plain HTTP. And GitHub refuses to set the flag (the certificate does not exist yet) on our legacy-build Pages sites, so it isn't actionable from our side anyway. Less serious than I made it sound.

"No FAQ" isn't a broken link problem. index.apt linked to faq.html, which doesn't exist. I removed the sentence, but writing an actual FAQ might be the better answer; I didn't want to fold that into a link fix.

Two decisions I'd like made in the pilot PRs

1. Hardcoded version in the dependency snippet. Goes stale every release. Alternative is omitting it and pointing at the badge — accurate, not copy-pasteable. Currently: version plus a note to check the badge.
2. Status wording. plexus-i18n says "maintained, but quiet by design — expect dependency updates rather than features". I think stating that plainly beats letting people infer abandonment from a Dependabot-only commit history, but it's a judgement call about how we want to be seen.

Whatever is decided there gets applied to all 17.

Still to come

• The other 15 READMEs, gated on pilot feedback.
• <description> for plexus-interactivity, plexus-interpolation, plexus-io — folded into their README PRs rather than opened separately.
• A workflow_dispatch site-publishing workflow. Not started: it needs a decision on whether the shared workflow pushes to gh-pages with GITHUB_TOKEN, and it means a caller workflow in each repo, so it's a change to the build rather than to documentation. Worth its own discussion once the above has settled.
• plexus-sec-dispatcher has no maven-scm-publish-plugin configuration, so the documented publish command doesn't work there. A build bug; I'll file it separately rather than bury it here.

Not doing

Code of conduct, licence-header normalisation, topic renaming, site.xml unification, and content for the four empty component sites. Reasoning is in the issue body and in #60. Argue with any of it.