Repository navigation
Documentation cleanup across the org: plan and tracking #58
Description
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.mdin this repo is still GitHub's placeholder template ("Hi there 👋", followed by the commented-out starter prompts). It's the first thing anyone sees atgithub.com/codehaus-plexus.- No
SECURITY.mdanywhere in the org, although plexus-archiver has 5 published advisories. There's no documented private reporting channel. - No
CONTRIBUTING.mdand 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 bindpublish-scmtosite-deployand carry the comment "mono-module doesn't require site:stage". plexus-sec-dispatcher documents a publish command but has noscm-publishconfiguration at all — that one is a build bug, and I'll file it separately.
Sites
- Two links on the landing page 404:
./faq.html, andwriting-components-trail/index.html— the latter is insite.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.xmladvertises 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.htmlasks contributors to paste a "Copyright 2007 The Codehaus Foundation" header and to downloadmaven-idea-codestyle.xmlinto~/.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.
Activity
Replace placeholder org profile with a real overview
Add SECURITY, CONTRIBUTING, RELEASING and issue/PR templates
slachiewicz commentedon Aug 8, 2026
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.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-i18nandplexus-interactivityhadhttp://homepage URLs. Nowhttps://.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.
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:
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 —
— 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-testingandplexus-build-apido have it enabled, and their Pages configuration is otherwise byte-identical (samelegacybuild type, samegh-pagessource, 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:
plexus-languagesplexus-build-api.githubplexus-xml,plexus-languages,plexus-testing,plexus-build-apiThe 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.Add a project description to the POM
Add a project description to the POM
slachiewicz commentedon Aug 8, 2026
Open for review
Eight PRs. Nothing is merged; the structural ones can sit for the 72 hours.
Org-wide files —
codehaus-plexus/.githubSite —
codehaus-plexus.github.io, stacked, review in orderavailable-componentsretired to a pointer.README skeleton — pilots
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
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.aptlinked tofaq.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
Whatever is decided there gets applied to all 17.
Still to come
<description>for plexus-interactivity, plexus-interpolation, plexus-io — folded into their README PRs rather than opened separately.workflow_dispatchsite-publishing workflow. Not started: it needs a decision on whether the shared workflow pushes togh-pageswithGITHUB_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-dispatcherhas nomaven-scm-publish-pluginconfiguration, 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.
Describe the parent POM as what it is
Rewrite README with usage, status and version guidance
Add a project description to the POM
Rewrite README with usage, status and version guidance
Add a project description to the POM
Fix two broken site links and the wrong mailing list
Rewrite the overview as the component index, retire available-components
Point contributors at CONTRIBUTING; label the retired container docs
Point contributors at CONTRIBUTING; label the retired container docs
21 remaining items
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
Rewrite README with usage, status and version guidance
slachiewicz commentedon Aug 8, 2026
Labels: survey, and a unified set applied across the org
Adding this to the settings log, since most of it isn't PR-able.
I surveyed the labels on all 19 active repos before changing anything: 246 label definitions, and 5,514 label applications across every issue and PR. Two problems.
The colours were never coordinated.
maintenanceexists in 18 repos with 18 different random hex colours —#02570C,#47F4DD,#EC4614,#240C22, and so on.buildis in 6 repos with 6 colours,breaking5 with 5,chore3 with 3. Same label, same meaning, different colour in every repo. On top of that, 14 repos still carry the pre-2018 GitHub default palette with no descriptions (bug #fc2929,enhancement #84b6eb); only plexus-xml, plexus-testing, plexus-build-api and this repo have the current one.The shared release-drafter config had drifted from reality. It categorises on 24 labels, of which 13 exist in no repo at all (
major-enhancement,major-rfe,major-bug,feature,rfe,regression,developer,test,deprecated,dependency,dependency-upgrade,skip-changelog). Those categories can never match anything. Meanwhilemaintenance— the third most-used label in the org — was reachable only through thechore/internalaliases that nobody applies.Usage is heavily concentrated. Six labels are 92% of all applications:
dependenciesdocumentationjavahelp wantedgithub_actionsbuildenhancementbreakingmaintenancebugTASK,duplicate,good first issueWhat I applied
A canonical set of 19 labels, now live on all 19 repos (0 errors). Colours are assigned by family so that hue carries meaning:
breakingremoveddeprecatedbugenhancementdocumentationmaintenancebuildtestdependenciesjavagithub_actionshelp wantedgood first issuequestionneed-rebaseno-changelogrevertedwontfixdependencieskeeps#0366D6exactly, because Dependabot recreates it at that colour if it is ever deleted.This step only created and recoloured labels. Nothing was deleted and no issue was relabelled.
good first issuealso went from 4 repos to all 19, which matters for anyone arriving from outside.Two PRs
labels.tsv(the canonical set) andsync-labels.sh(idempotent, dry-run by default) so this is reproducible rather than a one-off, and rewrites the sharedrelease-drafter.ymlso config and labels finally agree._extends. The copy uses the singularlabel:key in five places; release-drafter only honourslabels:, so Removed, Deprecated, Documentation, Build and Tests have been silently dead in that repo's drafts.Deliberately not done yet
Retiring the leftovers needs a second pair of eyes, so it's held for review:
fix/bugfix→bug,chore/internal→maintenance,plugins→dependencies, and deletingTASK(0 uses),java8(6),hacktoberfest-accepted(2),duplicate(0) andinvalid(1). The last two because GitHub's native Duplicate and Not planned close reasons now cover them.sync-labels.sh --prunemoves affected issues onto the replacement label before deleting anything, so nothing loses its classification.Three calls I'd particularly like disagreement on:
testanddeprecatedhave zero uses today. I added them because both are real release-note categories, and without them those PRs land under Maintenance. If carrying unused labels bothers you, these two are the ones to cut.java8(6 uses, plexus-classworlds and plexus-languages) is on the delete list as a historical marker. If it still means something for the 3.x/4.x split, I'll keep it.hacktoberfest-acceptedis only in plexus-archiver. Delete, or keep it there as a genuine October-only tool?slachiewicz commentedon Aug 8, 2026
Correction, and revisions after review
Two things in my comment above need fixing. I asked for a review of the proposal before pushing further, and it found a factual error plus several colour problems.
The plexus-utils claim was wrong
I wrote that plexus-utils had five release-note categories "silently dead" because its local config uses the singular
label:key instead oflabels:. That is not true. Release-drafter acceptslabel:as documented shorthand for a singlelabels:entry. From its README at v7.7.0, the version our workflow pins:and
schema.jsonat that tag declareslabelas a valid category property alongsidelabels. Removed, Deprecated, Documentation, Build and Tests have been working in plexus-utils the whole time.codehaus-plexus/plexus-utils#333 is still worth doing — it removes 59 lines of duplication that drift on their own — but it is deduplication, not a bug fix, and the PR description has been rewritten to say so. Apologies for the noise; I should have checked the schema before asserting it.
The colour scheme has changed — 17 labels, not 19
The set applied to all 19 repos has been revised. The rule now is explicit: hue carries meaning, and any two labels that can appear side by side must differ in both hue and text colour, since GitHub picks white or black from brightness. A three-step ramp in one hue is unreadable at label-pill size.
javais back to Dependabot's amber#FFA221. Putting it at#1D76DBwas the worst call in the original proposal:dependenciesandjavaco-occur on roughly 1,800 Maven PRs and sit side by side in every list, and I had made them near-identical blues. They are now deliberately opposite — dark blue with white text against amber with black text.build #006B75againsthelp wanted #008672— both dark teal, indistinguishable. Andneed-rebase #A371F7againstgood first issue #7057FF.buildmoved to brown#795548,need-rebaseto#D4C5F9.help wantedandgood first issuekeep GitHub's defaults, because its contributor-discovery surfaces key on those.no-changelog #EDEDEDwas near-invisible against GitHub's white background. Now#CFD3D7, withrevertedat near-black#24292F.github_actionsmoved to#79B8FF; the previous value sat right on GitHub's white/black text threshold, so its rendering was unpredictable.Two labels dropped from the canonical set
testis cut. Not simply unused — the shared config has advertised atestcategory for years and no repo ever grew the label. That's a finished experiment rather than an untried idea. Test-only changes here aremaintenance. (build, with 16 real uses, stays.)wontfixdropped, for consistency. I was deletingduplicateandinvalidas superseded by GitHub's native close reasons, and close as not planned supersedeswontfixby exactly the same argument. It keeps its definition where it has history.deprecatedstays despite 0 uses. Unliketest, it earns its place on semantics: for a library org, deprecations are API-lifecycle events consumers must see in the release notes.Changed policy: history-bearing labels are no longer deleted
This is the correction I'm most glad about. Deleting a label in GitHub strips it from every past issue permanently, with no undo. My original plan deleted
java8(6 uses) andhacktoberfest-accepted(2) outright, which would have destroyed real history to save one row in a label picker.New policy: stop propagating them, but leave them defined where they carry history.
java8,hacktoberfest-accepted,invalidandwontfixall stay. OnlyTASKandduplicate— 0 uses each — get deleted.--prunenow refuses to delete any label that is still in use, and still migrates issues onto the replacement before removing a merged label.One addition
The strongest objection to the original proposal was that it fixed the state without fixing the process — the 18-random-colours situation happened because there was a convention and nothing enforcing it, so we'd be back here in two years. #64 now also adds a weekly
label-syncworkflow. Its dry run is a real drift report: it diffs live labels againstlabels.tsv, prints only what differs and exits non-zero.LABEL_SYNC_TOKENsecret — a PAT with read/write Issues across the org, sinceGITHUB_TOKENis scoped to a single repo and can't write labels elsewhere. I don't have org admin, so someone else has to create it, and until then the workflow can only fail. Say the word and I'll drop the file from the PR until the secret exists.Add the Publish Site workflow
Add the Publish Site workflow
slachiewicz commentedon Aug 18, 2026
Closing this as done. The four passes in the plan landed, and what remains needs permissions nobody on this thread has, so tracking it here keeps an issue open that no one can act on.
What landed
Checked against the live API and the current file contents rather than against this thread.
available-componentsretired to a pointer (Reusing workflows #18), Get Involved rewritten and the retired container docs relabelled (Bump actions/setup-java from 3.0.0 to 3.1.0 #19). No page moved and no URL changed.plexus-i18n,plexus-interactivity,plexus-interpolation, andplexus-ioall have one, so no generated homepage inherits the parent's "full software stack" text.plexus-sec-dispatcherhasmaven-scm-publish-pluginconfiguration, so its documented publish command works.Decided against, after the fact
The plan asked for a shared, manually dispatched site-publishing workflow. It was added in #62 and removed again in #73, so the answer turned out to be no rather than not yet. The "still to come" list above is stale on that point.
The code of conduct and the FAQ both stand as written in the plan. Neither drew an argument in the ten days this was open.
Outstanding, needs an org owner
Two items need admin on repositories where the people in this thread have push only. Both are listed with the command to run.
Private vulnerability reporting is off on four repositories. This one has a real consequence: SECURITY.md tells a reporter to use a button that isn't enabled on
plexus-xml,plexus-languages,plexus-testing, orplexus-build-api, so a reporter there has no private channel and may file publicly instead.Five repositories still have no description. Each is written from that repository's own README.
Outstanding, anyone can do
plexus-build-apiis the one README that never got the skeleton. It has no coordinates, no status section, and no Java baseline. Push access is enough to fix it.This comment was created with AI assistance.