This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-doap-plugin.git
commit 729026c22025ea3d6d490213d060252aa4ff1ad2 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Sat Nov 14 10:04:36 2026 +0100 Rewrite README for this plugin and add AGENTS.md --- AGENTS.md | 71 ++++++++++++++++++++++++++++++++++++++++ README.md | 110 +++++++++++++++++++++++++++----------------------------------- 2 files changed, 118 insertions(+), 63 deletions(-) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cae1a66 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,71 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +# Working on the Maven DOAP Plugin + +These notes cover what the code and POM do not make obvious, for contributors and coding agents. + +## Layout + +- `src/main/java/org/apache/maven/plugin/doap/DoapMojo.java` is the single `doap:generate` goal; + `DoapUtil` holds the RDF writing helpers and `options/ASFExtOptionsUtil` the ASF rules (the + accepted categories and programming languages, and the category resource URI). +- `src/main/mdo/*.mdo` are Modello models. `DoapOptions`, `ASFExtOptions`, `ExtOptions`, + `DoapArtifact` and `Standard` are generated from them into + `target/generated-sources/modello`: edit the model, never the generated class. Option defaults + live in the models. +- `src/main/resources/doap-person*.properties` are translated messages (de, en, es, fr). The + `reporting` profile adds the l10n plugin's translation report for them. + +## Build + +- Floors: Java 8 (`maven.compiler.release`), Maven 3.9.0 (`<prerequisites>`). The build compiles + against Maven 3.9.x and Resolver 1.9.x; Dependabot ignores Maven 3.10+, Resolver 2.x and + SLF4J 2.x on purpose (see `.github/dependabot.yml`). +- Spotless (palantir-java-format for Java, sortpom for the POM) runs `apply` at `process-sources` + locally, so a normal build reformats your changes, and `check` when the `CI` environment variable + is set (the `format` profile in maven-parent). It does not format Markdown. +- Commands: + - `mvn verify`: unit tests. + - `mvn -Prun-its verify`: unit tests and the invoker integration tests. + - `mvn -Prun-its verify -Dinvoker.test=basic`: one integration test. + - `mvn site`: the site, from `src/site`. + +## Tests + +- Unit tests use JUnit 5 and maven-plugin-testing-harness 3.5.x: + `@MojoTest(realRepositorySession = true)`, `@InjectMojo` and `@Basedir` with fixtures under + `src/test/resources/unit/`. The harness hands the mojo a Mockito mock `MavenSession`; stub + anything the mojo reads from it. `DoapMojoTest#setUp` stubs `getProjectBuildingRequest()`, which + `DoapMojo` needs to resolve the POM of a configured `<artifact>`. +- Integration tests are in `src/it/` (`basic`, `doapfile`, `minimal`, `MDOAP-38`). Each has a + `verify.groovy`; `MDOAP-38` expects the build to fail. +- Namespace URIs such as `http://usefulinc.com/ns/doap#` and + `http://projects.apache.org/ns/asfext#` are identifiers, not links. Keep them on `http`; the + tests assert the literal values. + +## Site + +- `.md.vm` pages are Velocity templates: `##` starts a comment, so they use Setext headings + (`----` underlines), and a literal `$` is written as `${esc.d}`. +- Keep page names and `<a id="...">` anchors stable: they are published, and `DoapMojo` prints + a link to `usage.html#DOAP_ASF_Configuration` when ASF validation fails. + +## Pull requests + +- Pull requests are squash- or rebase-merged. Release Drafter builds the release notes from pull + request titles and labels, so the title must read as a release note and every pull request + needs a label. diff --git a/README.md b/README.md index 2b95c95..121505c 100644 --- a/README.md +++ b/README.md @@ -14,72 +14,56 @@ See the License for the specific language governing permissions and limitations under the License. --> -Contributing to [Apache Maven DOAP Plugin](https://maven.apache.org/plugins/maven-doap-plugin/) -====================== +# [Apache Maven DOAP Plugin](https://maven.apache.org/plugins/maven-doap-plugin/) [][license] -[](https://search.maven.org/artifact/org.apache.maven.plugins/maven-doap-plugin) -[][build] -[][test-results] - - -You have found a bug, or you have an idea for a cool new feature? Contributing -code is a great way to give something back to the open source community. Before -you dig right into the code, there are a few guidelines that we need -contributors to follow so that we can have a chance of keeping on top of -things. - -Getting Started ---------------- - -+ Make sure you have a [GitHub account](https://github.com/signup/free). -+ If you're planning to implement a new feature, it makes sense to discuss your changes - on the [dev list][ml-list] first. - This way you can make sure you're not wasting your time on something that isn't - considered to be in Apache Maven's scope. -+ Submit a ticket for your issue, assuming one does not already exist. - + Clearly describe the issue, including steps to reproduce when it is a bug. - + Make sure you fill in the earliest version that you know has the issue. -+ Fork the repository on GitHub. - -Making and Submitting Changes --------------- - -We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is the -main channel of communication for contributors. -There are some guidelines which will make applying PRs easier for us: -+ Create a topic branch from where you want to base your work (this is usually the master branch). - Push your changes to a topic branch in your fork of the repository. -+ Make commits of logical units. -+ Respect the original code style: by using the same [codestyle][code-style], - patches should only highlight the actual difference, not being disturbed by any formatting issues: - + Only use spaces for indentation. - + Create minimal diffs - disable on save actions like reformat source code or organize imports. - If you feel the source code should be reformatted, create a separate PR for this change. - + Check for unnecessary whitespace with `git diff --check` before committing. - -+ Make sure you have added the necessary tests (JUnit/IT) for your changes. -+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was accidentally broken. -+ Submit a pull request to the repository in the Apache organization. - -If you plan to contribute on a regular basis, please consider filing a [contributor license agreement][cla]. - -Additional Resources --------------------- - -+ [Contributing patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch) -+ [Contributor License Agreement][cla] -+ [General GitHub documentation](https://help.github.com/) -+ [GitHub pull request documentation](https://help.github.com/send-pull-requests/) -+ [Apache Maven X Account](https://x.com/ASFMavenProject) -+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org) -+ [Apache Maven Mastodon Account](https://mastodon.social/deck/@[email protected]) +[][central] +[][reproducible] +[][verify] +The DOAP Plugin generates a [Description of a Project (DOAP)](https://github.com/ewilderj/doap) +RDF file from a project's POM, so the project metadata is kept in one place. For Apache projects +it also writes the ASF extensions (PMC, chair, standards) and fails the build when a field the +[ASF DOAP guidelines](https://projects.apache.org/guidelines.html) require is missing. + +The plugin runs on Java 8 or later and requires Maven 3.9.0 or later. + +## Usage + +Generate the DOAP file into `target/site/doap_<artifactId>.rdf`: + +```shell +mvn doap:generate +``` + +To publish it with the project site, bind the `generate` goal to the `site` phase. The site +documents the [goal parameters](https://maven.apache.org/plugins/maven-doap-plugin/generate-mojo.html), +[pure DOAP and ASF configurations](https://maven.apache.org/plugins/maven-doap-plugin/usage.html), +[site integration](https://maven.apache.org/plugins/maven-doap-plugin/examples/with-site-plugin.html) +and an [FAQ](https://maven.apache.org/plugins/maven-doap-plugin/faq.html). + +## Contributing + +Report bugs and feature requests in [GitHub Issues][issues] and discuss larger changes on the +[developer mailing list][ml-list]. Build conventions, test layout and the pitfalls of this +repository are in [AGENTS.md](AGENTS.md). + +Run the unit tests and integration tests before opening a pull request: + +```shell +mvn -Prun-its verify +``` + +Pull requests are squash- or rebase-merged, and Release Drafter builds the release notes from +pull request titles and labels, so give each pull request a title that reads as a release note. + +## Releasing + +Follow the [Maven project release procedure](https://maven.apache.org/developers/release/maven-project-release-procedure.html). [license]: https://www.apache.org/licenses/LICENSE-2.0 +[central]: https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-doap-plugin +[reproducible]: https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-doap-plugin/README.md +[verify]: https://github.com/apache/maven-doap-plugin/actions/workflows/maven-verify.yml +[issues]: https://github.com/apache/maven-doap-plugin/issues [ml-list]: https://maven.apache.org/mailing-lists.html -[code-style]: https://maven.apache.org/developers/conventions/code.html -[cla]: https://www.apache.org/licenses/#clas -[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index -[test-results]: https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-doap-plugin/job/master/lastCompletedBuild/testReport/ -[build]: https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-doap-plugin/job/master/
