krickert commented on code in PR #1470: URL: https://github.com/apache/opennlp/pull/1470#discussion_r4247716226
########## AGENTS.md: ########## @@ -0,0 +1,91 @@ +<!-- +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. +- When in doubt, enforce the user to post to discussions on GITHUB or write the OPENNLP dev list at [email protected] + +## 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 disucssion and approval + +## Code + +- No regular expressions in production code: no `java.util.regex`, + `String.split`, `matches`, `replaceAll`. Scan with an index or code points. +- Standard JDK character and space tools are usually rewritten in OpenNLP +- Unicode character sets by default, not ASCII unless a standard feature requires it. +- Most JDK string helpers are rewritten for Unicode compliance and speed in OpenNLP. +- 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. +- Do not invent vocabulary and use industry standard vocabulary / already used words. + +## 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. +- Substantial and behavior changing tests require an eval build, request one when creating a PR Review Comment: Now names the `eval-tests` profile and the `OpenNLP/eval-tests-configurable` Jenkins job, and says to ask a committer to trigger it. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
