Skip to content

Documentation cleanup across the org: plan and tracking #58

Closed

Description

@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.

Activity

  1. slachiewicz commented on Aug 8, 2026

    @slachiewicz
    MemberAuthor

    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.

  2. slachiewicz commented on Aug 8, 2026

    @slachiewicz
    MemberAuthor

    Open for review

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

    Org-wide files — codehaus-plexus/.github

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

    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.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.

  3. 21 remaining items

  4. slachiewicz commented on Aug 8, 2026

    @slachiewicz
    MemberAuthor

    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. maintenance exists in 18 repos with 18 different random hex colours — #02570C, #47F4DD, #EC4614, #240C22, and so on. build is in 6 repos with 6 colours, breaking 5 with 5, chore 3 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. Meanwhile maintenance — the third most-used label in the org — was reachable only through the chore/internal aliases that nobody applies.

    Usage is heavily concentrated. Six labels are 92% of all applications:

    label uses label uses
    dependencies 2366 documentation 20
    java 1801 help wanted 17
    github_actions 503 build 16
    enhancement 323 breaking 11
    maintenance 222 everything else ≤9 each
    bug 187 TASK, duplicate, good first issue 0

    What 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:

    family labels reading
    red breaking removed deprecated bug something is broken or going away
    green / blue / amber / teal enhancement documentation maintenance build test kind of change
    blue ramp dependencies java github_actions Dependabot noise, skippable as a block
    purple / green help wanted good first issue question need-rebase needs a human
    grey no-changelog reverted wontfix invisible to the release notes

    dependencies keeps #0366D6 exactly, 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 issue also went from 4 repos to all 19, which matters for anyone arriving from outside.

    Two PRs

    • Unify the label taxonomy across the org #64 — adds labels.tsv (the canonical set) and sync-labels.sh (idempotent, dry-run by default) so this is reproducible rather than a one-off, and rewrites the shared release-drafter.yml so config and labels finally agree.
    • Use the shared release-drafter config instead of a local copy plexus-utils#333 — plexus-utils is the only repo with a full copy of the release-drafter config instead of _extends. The copy uses the singular label: key in five places; release-drafter only honours labels:, 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 deleting TASK (0 uses), java8 (6), hacktoberfest-accepted (2), duplicate (0) and invalid (1). The last two because GitHub's native Duplicate and Not planned close reasons now cover them. sync-labels.sh --prune moves affected issues onto the replacement label before deleting anything, so nothing loses its classification.

    Three calls I'd particularly like disagreement on:

    • test and deprecated have 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-accepted is only in plexus-archiver. Delete, or keep it there as a genuine October-only tool?
  5. slachiewicz commented on Aug 8, 2026

    @slachiewicz
    MemberAuthor

    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 of labels:. That is not true. Release-drafter accepts label: as documented shorthand for a single labels: entry. From its README at v7.7.0, the version our workflow pins:

    | label | Shorthand for one labels entry. |

    and schema.json at that tag declares label as a valid category property alongside labels. 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.

    • java is back to Dependabot's amber #FFA221. Putting it at #1D76DB was the worst call in the original proposal: dependencies and java co-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.
    • Two collisions I missed. build #006B75 against help wanted #008672 — both dark teal, indistinguishable. And need-rebase #A371F7 against good first issue #7057FF. build moved to brown #795548, need-rebase to #D4C5F9. help wanted and good first issue keep GitHub's defaults, because its contributor-discovery surfaces key on those.
    • no-changelog #EDEDED was near-invisible against GitHub's white background. Now #CFD3D7, with reverted at near-black #24292F.
    • github_actions moved 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

    • test is cut. Not simply unused — the shared config has advertised a test category for years and no repo ever grew the label. That's a finished experiment rather than an untried idea. Test-only changes here are maintenance. (build, with 16 real uses, stays.)
    • wontfix dropped, for consistency. I was deleting duplicate and invalid as superseded by GitHub's native close reasons, and close as not planned supersedes wontfix by exactly the same argument. It keeps its definition where it has history.
    • deprecated stays despite 0 uses. Unlike test, 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) and hacktoberfest-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, invalid and wontfix all stay. Only TASK and duplicate — 0 uses each — get deleted. --prune now 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-sync workflow. Its dry run is a real drift report: it diffs live labels against labels.tsv, prints only what differs and exits non-zero.

    ⚠️ It needs a LABEL_SYNC_TOKEN secret — a PAT with read/write Issues across the org, since GITHUB_TOKEN is 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.

  6. slachiewicz commented on Aug 18, 2026

    @slachiewicz
    MemberAuthor

    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.

    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, or plexus-build-api, so a reporter there has no private channel and may file publicly instead.

    gh api -X PUT repos/codehaus-plexus/plexus-xml/private-vulnerability-reporting
    gh api -X PUT repos/codehaus-plexus/plexus-languages/private-vulnerability-reporting
    gh api -X PUT repos/codehaus-plexus/plexus-testing/private-vulnerability-reporting
    gh api -X PUT repos/codehaus-plexus/plexus-build-api/private-vulnerability-reporting
    

    Five repositories still have no description. Each is written from that repository's own README.

    gh api -X PATCH repos/codehaus-plexus/plexus-languages  -f description="Reads Java module descriptors and splits paths into a classpath and a module path"
    gh api -X PATCH repos/codehaus-plexus/plexus-build-api  -f description="Connects IDEs to Maven for incremental builds, file markers, and refresh notifications"
    gh api -X PATCH repos/codehaus-plexus/plexus-xml        -f description="Holds the Xpp3Dom classes and XML pull parser that used to live in plexus-utils"
    gh api -X PATCH repos/codehaus-plexus/plexus-testing    -f description="Injects JSR-330 components into JUnit 5 tests"
    gh api -X PATCH repos/codehaus-plexus/.github           -f description="Holds the shared GitHub Actions workflows and community health files for every Codehaus Plexus repository"
    

    Outstanding, anyone can do

    plexus-build-api is 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions