This is an automated email from the ASF dual-hosted git repository.
krickert pushed a commit to branch feat/GH-1453-agents-md
in repository https://gitbox.apache.org/repos/asf/opennlp.git
The following commit(s) were added to refs/heads/feat/GH-1453-agents-md by this
push:
new fd4b70f1b GH-1453: Add AGENTS.md
fd4b70f1b is described below
commit fd4b70f1bf33738e9b73ea418f0342e46c2f4243
Author: Kristian Rickert <[email protected]>
AuthorDate: Sun Oct 11 02:58:32 2026 -0400
GH-1453: Add AGENTS.md
Short rules for AI coding agents and the people who use them: the AI
policy, build steps, the code, Javadoc and test conventions the project
enforces, and the commit format.
Signed-off-by: Kristian Rickert <[email protected]>
---
AGENTS.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 84 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..b0afb4cbb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,84 @@
+<!--
+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.
+
+## Policy
+
+- AI tools may help write code. The committer reviews every line, can explain
+ it, and is responsible for it.
+- Disclose AI help in the commit message, for example an `Assisted-by:`
+ trailer. Do not add model identifiers.
+- Agents do not open pull requests, post comments, file issues or reply to
+ reviewers on their own. A human writes or reviews and sends every message,
+ and marks any quoted AI text as such. This follows the
+ [Apache Lucene AI
policy](https://github.com/apache/lucene/blob/main/AI_POLICY.md).
+- Never include third-party code or data without a compatible license.
+
+## 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.
+
+## Code
+
+- No regular expressions in production code: no `java.util.regex`,
+ `String.split`, `matches`, `replaceAll`. Scan with an index or code points.
+- Use existing helpers before writing new ones. Check the JDK, then
+ `ParamChecks`, `StringUtil`, `AsciiChars`, `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.
+
+## 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.
+
+## 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.
