diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..c5af6be --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,52 @@ +name: Bug report +description: Something in a Plexus library behaves incorrectly +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting. For a security vulnerability, please **stop** and follow + [SECURITY.md](https://github.com/codehaus-plexus/.github/blob/master/SECURITY.md) instead — don't file it here. + + - type: input + id: version + attributes: + label: Version + description: Which version of this artifact are you using? + placeholder: "e.g. plexus-archiver 4.12.0" + validations: + required: true + + - type: input + id: environment + attributes: + label: JDK and Maven version + description: Output of `mvn -v` is ideal. + placeholder: "e.g. Maven 3.9.11, Temurin 21.0.5, Linux" + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: What happened instead? + description: Include the stack trace or the relevant `mvn -e` output if there is one. + validations: + required: true + + - type: textarea + id: reproducer + attributes: + label: How can we reproduce it? + description: > + A minimal project, a failing test, or a short code snippet. This is usually the + difference between an issue that gets fixed and one that stalls. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d285c33 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ + + +### What does this change? + + + +### Related issue + + + +### Anything reviewers should look at closely? + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..42a8118 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contributing to Codehaus Plexus + +This applies to every repository in the [codehaus-plexus](https://github.com/codehaus-plexus) organisation. + +These libraries sit underneath Apache Maven and most of its plugins, so a regression here reaches a very long way. That shapes the advice below more than any style preference does. + +## Where to ask + +**GitHub Issues, on the repository concerned.** That is where the maintainers are. There is no Plexus mailing list — if you find one referenced in older documentation, it is defunct. + +If you aren't sure which repository owns the behaviour you're seeing, open the issue wherever seems closest and we'll move it. + +## Building + +``` +mvn verify +``` + +That's it — no profile or local setup required. CI runs the equivalent of: + +``` +mvn --batch-mode --errors --show-version verify javadoc:javadoc +``` + +across JDK 8, 21 and 25 on Linux, Windows and macOS, using Maven 3.9.11. If your change builds on your machine but you can't easily test the other JDKs, open the pull request anyway and let CI tell you. + +Some repositories have integration tests behind a profile, usually `-Prun-its`. Check the repository's own README. + +## Java baseline + +Most projects still target **Java 8**, inherited from the parent POM. A few have moved on — `plexus-sec-dispatcher` and `plexus-xml` 4.x require **Java 17**, in step with Maven 4. + +Check the `javaVersion` property in the project's `pom.xml` before reaching for a newer API. Raising a baseline is a deliberate, separate decision, not something to slip into a feature PR. + +## Formatting + +Formatting is enforced by the build, so don't hand-format and don't reformat code you aren't otherwise touching: + +``` +mvn spotless:apply +``` + +This applies [palantir-java-format](https://github.com/palantir/palantir-java-format), sorts imports, and tidies POMs. If CI fails on `spotless:check`, running the command above and committing the result is the whole fix. + +You may still find older documentation telling you to import `maven-eclipse-codestyle.xml` or `maven-idea-codestyle.xml` into your IDE. That predates Spotless and no longer reflects what the build enforces. + +## Licence headers + +New files need the standard Apache-2.0 header used by the surrounding files in that repository. Modello is MIT — match what's already in the file you're next to. + +Please **don't** update or "normalise" existing copyright headers, including the older `Codehaus Foundation` ones. They record who contributed what, and changing them is not ours to do. + +## Pull requests + +- One concern per pull request. Mechanical cleanups and behaviour changes in the same diff are much harder to review and much slower to merge. +- Explain *why* in the description. The what is visible in the diff. +- Add a test. If the change is genuinely untestable, say so and why. +- Keep public API compatible. These artifacts are consumed transitively by essentially the whole Maven plugin ecosystem, so a source- or binary-incompatible change needs discussion in an issue first. Deprecate rather than remove; the deprecation javadoc should say what to use instead. +- Reference the issue the PR addresses, if there is one. + +Maintainers may squash on merge, so don't worry about a tidy commit history within a branch. + +## Reporting a bug + +The useful ones say which version you're on, which JDK and Maven version, what you expected, and what happened instead. A short reproducer beats a long description. If it involves a build failure, the output of `mvn -e` helps. + +## Security + +Please don't open a public issue for a vulnerability. See [SECURITY.md](SECURITY.md). + +## For maintainers + +Releasing and site publishing are documented in [RELEASING.md](RELEASING.md). diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..42f28d8 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,75 @@ +# Releasing and publishing sites + +For maintainers. This is the single reference for both — the per-repository READMEs used to each carry their own version of it, and they had drifted into four mutually inconsistent recipes. + +## One-time setup + +Artifacts go to Maven Central through the Sonatype Central Portal. Add the token to your personal `~/.m2/settings.xml`: + +```xml + + + + sonatype-central-portal + + + + + +``` + +Generate the token pair at under your account. It is a token, not your account password. + +You also need a published GPG key — releases are signed. + +## Releasing + +Releases are cut with `maven-release-plugin` from the default branch: + +``` +mvn release:prepare +mvn release:perform +``` + +`release:prepare` tags and bumps versions; `release:perform` builds from the tag and stages to the Central Portal. Then publish the staged deployment from the Central Portal UI. + +Afterwards: + +1. Check the [release drafter](https://github.com/codehaus-plexus/.github/blob/master/.github/workflows/release-drafter.yml) draft on the GitHub releases page, edit it into shape, and publish it. Release notes live on GitHub releases, not in the repository. +2. Publish the site, so the Javadoc and dependency reports on the site match what is now on Central. See below. + +## Publishing the site + +Sites are published to each repository's own `gh-pages` branch and served at `https://codehaus-plexus.github.io//`. The parent POM sets `maven-site-plugin` to `skipDeploy`, so the publishing is done by `maven-scm-publish-plugin` against `scm.developerConnection`, not by `site:deploy`. + +**Most repositories are single-module**, and bind `scm-publish:publish-scm` to the `site-deploy` phase. For those, the whole command is: + +``` +mvn -Preporting clean verify site-deploy +``` + +That covers plexus-utils, plexus-xml, plexus-io, plexus-archiver, plexus-interpolation, plexus-classworlds, plexus-testing, plexus-i18n, plexus-resources and plexus-velocity. + +**Multi-module repositories need staging first**, because the site has to be assembled across modules before it is pushed: + +``` +mvn -Preporting clean verify site site:stage scm-publish:publish-scm +``` + +That covers modello, plexus-compiler, plexus-languages and plexus-interactivity. + +The `-Preporting` profile is what adds the Javadoc, JXR and surefire reports. Without it you publish a site with no API documentation, which is worse than not republishing at all. + +### Known gap + +`plexus-sec-dispatcher` has no `maven-scm-publish-plugin` configuration in its POM, so neither command above works there as written; the goal has to be invoked with `-Dscmpublish.content=target/site` by hand. This is a build bug rather than a documentation one and is tracked separately. + +## Why this isn't automated + +There is no workflow that publishes sites on release. That is deliberate for now: publishing puts content live with no review step, and Maven site builds break often enough — doxia, site plugin and JDK interactions — that we would rather a person saw the output. + +A manually-triggered (`workflow_dispatch`) workflow so that the command above becomes one button, without taking the release manager out of the loop, is the intended next step. + +## Snapshot deployment + +The shared `maven-deploy.yml` workflow currently has snapshot publishing disabled (the step is a placeholder that echoes and exits). Don't rely on snapshots being on Central; build locally with `mvn install` instead. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a40f7e7 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +This policy covers every repository in the [codehaus-plexus](https://github.com/codehaus-plexus) organisation. + +## Reporting a vulnerability + +**Please do not open a public issue or pull request for a security problem.** + +Report it privately through GitHub, using the **Report a vulnerability** button on the Security tab of the affected repository. That opens a private advisory visible only to the maintainers: + +> `https://github.com/codehaus-plexus//security/advisories/new` + +If you aren't sure which repository is affected, report against the one you believe is closest and say so in the report; we will move it. + +A report is most useful when it includes the affected artifact and version, how the issue can be triggered, and what an attacker gains. A reproducer is worth a great deal. + +## What happens next + +We will confirm the report, work on a fix privately, and publish a GitHub Security Advisory with a CVE when the fix is released. Where a fix isn't possible or the report turns out not to be a vulnerability, we will tell you that and why. + +Plexus is maintained by volunteers, so we cannot promise a response time. If a report goes unacknowledged for a couple of weeks, please feel free to nudge us in the advisory thread. + +We are glad to credit reporters in the advisory. Tell us how you would like to be named, or that you would rather not be. + +## Which versions get fixes + +Fixes go onto the current development line of the affected project, and are released from there. Whether a fix is also backported to an older line is decided case by case, based on how widely that line is still used — we do not maintain a fixed list of supported versions. + +## Scope + +This policy covers the code in this organisation's repositories and the artifacts published from them to Maven Central under `org.codehaus.plexus` and `org.codehaus.modello`. + +Archived repositories — listed on the [organisation profile](https://github.com/codehaus-plexus) — receive no fixes of any kind, including security fixes. If you find a vulnerability in one, we would still like to know, so we can point people away from it, but the answer will be to migrate rather than to patch.