GH-1453: Add AGENTS.md with rules for AI coding agents

AGENTS.md

@@ -0,0 +1,110 @@
+<!--
+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.
+-->
+
+# Notes for AI coding agents
+
+Short rules for agents working on Apache OpenNLP. Human contributors follow
+the same rules.
+
+## Layout
+
+- `opennlp-api`: the public interfaces and shared types such as `ParamChecks`.
+- `opennlp-core`: `opennlp-runtime` (the components), `opennlp-ml` (the shared
+  `opennlp-ml-commons` plus the maxent, perceptron, naive Bayes and libsvm
+  implementations, and `opennlp-dl` and `opennlp-dl-gpu` for ONNX models),
+  `opennlp-formats`, `opennlp-cli` and `opennlp-model-resolver`.
+- `opennlp-tools`: the end-user toolkit that bundles the core modules.
+- `opennlp-extensions`: Morfologik, spell checking and UIMA.
+- `opennlp-docs`: the manual in DocBook (`src/docbkx`).
+- `opennlp-eval-tests`: evaluations on reference corpora (see Tests).
+- `opennlp-distr`: the binary and source distributions.
+
+## Policy
+
+- AI tools may help write code. The committer reviews every line, can explain
+  it, and is responsible for it.
+- When AI contributed to a commit that a human authored and edited, disclose it
+  with a `Co-authored-by:` trailer naming the tool and its version and the model
+  and its version, following the
+  [ASF generative tooling guidance](https://www.apache.org/legal/generative-tooling.html).
+  The human is the author and signs off the commit (`git commit -s`).
+- Agents do not open pull requests, post comments, file issues or reply to
+  reviewers on their own. A human writes each message. Quoted AI output is
+  marked as such and accompanied by the human's comment.
+- Contributors who need AI translation, because English is not their first
+  language or for accessibility, quote and attribute the AI text and include
+  the original wording when possible.
+- Never include third-party code or data without a compatible license.
+- When in doubt, ask on GitHub Discussions or dev@opennlp.apache.org.
+
+## Build
+
+- JDK 21 and `./mvnw`. With `-pl`, add `-am`.
+- Run `./mvnw verify` on the touched modules before proposing a change;
+  checkstyle and forbiddenapis run there.
+- Do not introduce new dependencies without a discussion and approval.
+
+## Code
+
+- No regular expressions in production code: no `java.util.regex`,
+  `String.split`, `matches`, `replaceAll`. Scan with an index or code points.
+- Unicode character sets by default, not ASCII unless a standard feature requires it.
+- Use existing helpers before writing new ones. Check the JDK, then
+  `ParamChecks`, `StringUtil`, `UnicodeWhitespace` and the helpers of the
+  package you work in. A second copy of a helper is a bug.
+- Case mapping and trimming go through `StringUtil`
+  (`toLowerCase`, `toUpperCase`, `trimUnicodeWhitespace`), never the
+  locale-sensitive `String` methods.
+- Whitespace: define what counts (ASCII, Unicode, a single space) and use the
+  matching helper or constant. Do not hard-code `' '` or `"\\s+"`.
+- Formatting: two-space indents in Java, no tabs, no trailing whitespace,
+  files end with a newline. Match the indentation of the surrounding docbkx.
+- Reject bad arguments at the public API with `IllegalArgumentException` via
+  `ParamChecks`; never NPE from `Objects.requireNonNull`.
+- Malformed input data throws `InvalidFormatException`.
+- Name repeated literals as constants. Do not allocate in hot loops.
+- Serializable singletons need `readResolve()`; changed Serializable classes
+  need a new `serialVersionUID`.
+
+## Javadoc and comments
+
+- Every new or changed method gets short, accurate Javadoc. Overrides use
+  `{@inheritDoc}`. Write `@throws X Thrown if ...`. New public types get
+  `@since`.
+- Describe the contract, not the history. No "replaces the old regex",
+  issue numbers, or design narrative in source; that goes in the issue.
+- No em dashes.
+- Use the terms the code and the manual already use; do not invent new ones.
+
+## Tests
+
+- Test first for behavior changes: the test fails before the fix.
+- Many inputs go in a `@ParameterizedTest`, not a loop.
+- Reuse shared fixtures instead of copying helpers into each test class.
+- Assert exception type and message. Do not reimplement the code under test
+  as the expected value.
+- Do not add tests that repeat a case another test already covers.
+- Changes to models, training or default behavior need an eval build: the
+  `eval-tests` profile of `opennlp-eval-tests`, run on the ASF Jenkins job
+  `OpenNLP/eval-tests-configurable`. Ask a committer to trigger it and link the
+  run in the pull request.
+
+## Commits
+
+- Title: `GH-<issue>: <what changes for users>`. Body: a few plain sentences
+  on the change, not the history.
+- Update `opennlp-docs` when user-visible behavior changes.