From 12b022605c41e640a9c72a6d715a4c23990998b6 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Sat, 8 Aug 2026 19:40:39 +0200 Subject: [PATCH] Document what the parent POM actually configures The README was a badge and a line saying the canonical repository is this one. The site page said the parent 'defines common plugins, reporting and release configuration' and then went straight into settings.xml for the release manager - so a project inheriting this POM had no way to learn what it inherits. Both now cover the baselines, the enforcer rules, Spotless and where it applies vs checks, reproducible builds, the reporting profile, and what a child project still has to override. Corrects the release description. maven-release-plugin runs with releaseProfiles=plexus-release, which enables Njord, configured with autoPublish and publishingType=automatic - so the deployment publishes without a manual step in the Central Portal UI. The page implied otherwise by documenting only the token setup. Also warns that Spotless formats **/*.md and that parent 25 does not exclude src/site/markdown, which destroys Doxia front matter. Adds Plexus Build API, Sec Dispatcher and Testing to the Plexus Projects menu; all three were missing. Verified the site builds and all 17 entries resolve. Fixes the 'vie the Central Portal' typo. Part of codehaus-plexus/.github#58 --- README.md | 69 +++++++++++++++++++-- src/site/markdown/index.md | 123 +++++++++++++++++++++++++++++++++++-- src/site/site.xml | 3 + 3 files changed, 185 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index fe3c96bdc..79dbfade8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,67 @@ -Plexus Parent POM -================= +# Plexus Parent POM -[![Maven Central](https://img.shields.io/maven-central/v/org.codehaus.plexus/plexus.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.codehaus.plexus/plexus) +[![Maven Central](https://img.shields.io/maven-central/v/org.codehaus.plexus/plexus.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.codehaus.plexus/plexus) +[![GitHub CI](https://github.com/codehaus-plexus/plexus-pom/actions/workflows/maven.yml/badge.svg)](https://github.com/codehaus-plexus/plexus-pom/actions) +[![License](https://img.shields.io/github/license/codehaus-plexus/plexus-pom.svg?label=License)](https://www.apache.org/licenses/LICENSE-2.0) -The current master is now at https://github.com/codehaus-plexus/plexus-pom +The parent POM inherited by every project in the [Codehaus Plexus](https://github.com/codehaus-plexus) +organisation. It pins plugin versions, the Java and Maven baselines, formatting, reporting and the release +setup, so the individual projects carry almost no build configuration of their own. + +## Status + +Maintained. Released whenever plugin or dependency updates accumulate, roughly every couple of months. + +This is infrastructure for the Plexus projects rather than a general-purpose parent — it assumes Sonatype +Central Portal publishing, GitHub Pages site hosting and the organisation's shared CI workflow. You are +welcome to use it, but it is not designed to be neutral. + +## Using it + +```xml + + org.codehaus.plexus + plexus + 25 + +``` + +Check the badge above for the current version. + +Projects must override `distributionManagement/site` to point at their own `gh-pages` branch; everything +else is inherited. + +## What it configures + +- **Baselines** — Java 8 (`javaVersion`), Maven 3.6.3 minimum, UTF-8 sources +- **Enforcer** — Maven and JDK minimums, plus a rule rejecting dependencies whose bytecode is newer than + your compiler target +- **Formatting** — Spotless with palantir-java-format, sorted POMs, flexmark for Markdown. Applies locally, + checks in CI +- **Reproducible builds** — `project.build.outputTimestamp` is set and the results are verified by + [Reproducible Central](https://github.com/jvm-repo-rebuild/reproducible-central) +- **Reporting** — the `reporting` profile adds Javadoc, JXR, surefire, PMD/CPD and taglist +- **Releasing** — the `plexus-release` profile adds GPG signing, sources and a source-release assembly, and + enables [Njord](https://maveniverse.eu/docs/njord/) to publish to Central + +The [project site](https://codehaus-plexus.github.io/plexus-pom/) explains each of these, and lists every +[managed plugin version](https://codehaus-plexus.github.io/plexus-pom/plugin-management.html). + +## Requirements + +Java 8 or later to build a consuming project; Maven 3.6.3 or later (3.9.0 when releasing). + +## Documentation + +- [Project site](https://codehaus-plexus.github.io/plexus-pom/) +- [Release notes](https://github.com/codehaus-plexus/plexus-pom/releases) +- [Releasing and site publishing](https://github.com/codehaus-plexus/.github/blob/master/RELEASING.md) + +## Contributing + +See [CONTRIBUTING.md](https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md). Changes here +affect every project in the organisation, so a version bump that looks routine can break a downstream build +— please say in the PR description what you have checked. + +Please report security vulnerabilities privately — see +[SECURITY.md](https://github.com/codehaus-plexus/.github/blob/master/SECURITY.md), not a public issue. diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index d40ba7c63..0e339ed1c 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -1,10 +1,113 @@ # Plexus Parent POM -Plexus Parent POM defines common [plugins](./plugin-management.html), reporting and release configuration. +The parent POM inherited by every project in the [Codehaus Plexus](https://codehaus-plexus.github.io/) +organisation. It fixes plugin versions, the Java and Maven baselines, code formatting, reporting and the +release setup, so the individual projects carry almost no build configuration of their own. -## Preparing the environment for publishing vie the Central Portal +```xml + + org.codehaus.plexus + plexus + + +``` + +## What you get + +### Baselines + +| Setting | Value | +|---|---| +| Java (`javaVersion`) | 8 — sets `maven.compiler.source`, `target` and `release` | +| Minimum Maven to build | 3.6.3 (3.9.0 when releasing) | +| Source encoding | UTF-8 | +| Annotation processing | off (`maven.compiler.proc=none`) — enable it deliberately if you need it | + +Override `javaVersion` in your own POM to raise the baseline; `plexus-sec-dispatcher` and `plexus-xml` 4.x +set it to 17. + +### Enforced at build time + +`maven-enforcer-plugin` fails the build on a Maven version below the minimum, a JDK below the baseline, +and — via `extra-enforcer-rules` — on any **dependency containing bytecode newer than your compiler +target**. That last rule is the one that usually catches people: it means a dependency compiled for a +later JDK than you target is an error, not a runtime surprise. + +### Formatting + +Spotless, applied at `process-sources`: -Release manager should include the following sections in your personal `settings.xml`: +- Java — [palantir-java-format](https://github.com/palantir/palantir-java-format), unused imports removed, + import order `javax, java, all else, static` +- POMs — sorted with `sortPom` +- Markdown — flexmark + +The action depends on where you are. Locally (`!env.CI`) the `format` profile sets `spotless.action=apply`, +so a build **rewrites your sources**. In CI (`env.CI` set) the `format-check` profile sets it to `check`, +so the build fails instead. If CI fails on formatting, run `mvn spotless:apply` and commit. + +> Note that Spotless formats `**/*.md`. Parent 26 onward excludes `**/src/site/markdown/**`, because +> flexmark rewrites the fence closing a YAML front matter block and silently destroys a page's title and +> author. **Parent 25 does not have that exclusion** — if you are on 25 and keep site sources in Markdown, +> add the exclusion to your own POM. + +### Reproducible builds + +`project.build.outputTimestamp` is set, and every project here is verified by +[Reproducible Central](https://github.com/jvm-repo-rebuild/reproducible-central). Keep it set, and bump it +only as part of a release. + +### Reporting + +Project info reports are on by default. The `reporting` profile adds the rest — Javadoc, JXR, surefire, +PMD/CPD and taglist: + +``` +mvn -Preporting site +``` + +Building a site **without** `-Preporting` gives you a site with no API documentation, so always pass it +when publishing. + +### Publishing + +Snapshots and releases go to the Sonatype Central Portal. `distributionManagement` is inherited; +`site` **must be overridden** in each project, and points at that project's own `gh-pages` branch: + +```xml + + + github:gh-pages + ${project.scm.developerConnection} + + +``` + +`maven-site-plugin` runs with `skipDeploy`, so sites are published by `maven-scm-publish-plugin` rather +than `site:deploy`. + +## Releasing + +Full procedure, including site publishing, is in +[RELEASING.md](https://github.com/codehaus-plexus/.github/blob/master/RELEASING.md). The short version: + +``` +mvn release:prepare +mvn release:perform +``` + +`maven-release-plugin` is configured with `deploy` and +`plexus-release`, so `release:perform` activates the `plexus-release` +profile. That profile turns on GPG signing, attaches sources and a source-release assembly, and enables +[Njord](https://maveniverse.eu/docs/njord/), which is registered as a build extension. + +Njord is configured with `autoPublish=true` and `publishingType=automatic`, so the deployment is published +to Central **without a manual step in the Portal UI**. `njord.enabled` is `false` outside the release +profile, so ordinary builds are unaffected. + +### Release manager setup + +A Central Portal token in your personal `settings.xml`: ```xml sonatype-central-portal - jqhacker - SeCrEt + + ``` -Tokens can be obtained from https://central.sonatype.com/account +Tokens come from . It is a generated token pair, not your account +password. + +You also need a published GPG key, since releases are signed. + +## Reference +- [Plugin versions managed here](./plugin-management.html) +- [Dependency versions managed here](./dependency-management.html) +- [Contributing](https://github.com/codehaus-plexus/.github/blob/master/CONTRIBUTING.md) diff --git a/src/site/site.xml b/src/site/site.xml index 59edeea41..4123fe09b 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -51,6 +51,7 @@ + @@ -61,6 +62,8 @@ + +