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/)
 
 [![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)][license]
-[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-doap-plugin.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.plugins/maven-doap-plugin)
-[![Jenkins 
Status](https://img.shields.io/jenkins/s/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-doap-plugin/job/master.svg?)][build]
-[![Jenkins 
tests](https://img.shields.io/jenkins/t/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-doap-plugin/job/master.svg?)][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])
+[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-doap-plugin.svg?label=Maven%20Central)][central]
+[![Reproducible 
Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/plugins/maven-doap-plugin/badge.json)][reproducible]
+[![Verify](https://github.com/apache/maven-doap-plugin/actions/workflows/maven-verify.yml/badge.svg)][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/

Reply via email to