You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by "krickert (via GitHub)" <gi...@apache.org> on 2026/10/11 08:57:38 UTC

[PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

krickert opened a new pull request, #1470:
URL: https://github.com/apache/opennlp/pull/1470

   Adds AGENTS.md at the repository root: short rules for AI coding agents and the people who run them. It covers the AI policy (the committer reviews and owns AI output; agents do not post comments, issues or PRs on their own, following the Lucene AI policy), the build, the code conventions the project enforces (no regex in production code, existing helpers before new ones, StringUtil for case and whitespace, ParamChecks), Javadoc, tests and commit format.
   
   Fixes #1453


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6455215511

   No rush to merge, but looks like we can merge this.
   
   
   For tracking purposes - we went the vote for this 4 days ago:
   
   > Hi all, 
   > This is a call for lazy consensus to adopt the AGENTS.md file and our policy for working with AI-generated content as proposed in apache/opennlp#1470. The policy follows the current ASF guidance (RAI / legal) linked in the PR and will be revisited once the ASF publishes further guidance. This vote will be open for at least 72 hours (or longer if more time is suggested). If there are no objections, it is accepted. Please reply with -1 and your reasoning if you object. Discussion of the content can stay in the existing [DISCUSS] thread or on the PR. 
   > Thanks, Kristian
   
   @mawiesne @rzo1 my vote - merge now or anytime you feel like 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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4242492626


##########
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).

Review Comment:
   The linked Lucene policy requires project comments to be written by humans; it does not permit AI-generated messages merely because a human reviews and sends them. It allows AI context only when quoted, disclosed, and accompanied by human commentary, so this wording weakens the policy the PR says it follows.



##########
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 dev@opennlp.apache.org

Review Comment:
   “Enforce the user to” is not idiomatic and makes this fallback instruction unclear. Use a direct request and the project’s standard capitalization.
   
   This issue also appears on line 75 of the same file.



##########
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 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 disucssion and approval

Review Comment:
   Correct the spelling of “discussion.”



##########
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 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 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:
   “Eval build” is not defined elsewhere in the repository; the concrete Maven profile is named `eval-tests` (`opennlp-eval-tests/pom.xml:137`). An agent cannot determine what build to request or how to trigger it, so name the profile or CI job and the request procedure explicitly.



##########
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

Review Comment:
   Issue #1453 explicitly asks this file to explain how the application is laid out, but no repository or module layout is included. Add a short section identifying where the API, runtime, CLI, tools, documentation, extensions, and evaluation tests live; the existing module summary in `README.md:69-87` can be condensed rather than duplicated in full.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "rzo1 (via GitHub)" <gi...@apache.org>.
rzo1 commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4301860604


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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.
+  The one exception, and the build check that enforces the rule, are described
+  in [CONTRIBUTING.md](.github/CONTRIBUTING.md#regular-expressions-in-production-code).
+- 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

Review Comment:
   This can encourage agents to produce unnecessary comments for private implementation methods or trivial edits.
   
   Maybe we can rephrase to require Javadoc for new public and protected APIs and for changes affecting documented interfaces (or contracts). Preserve existing documentation elsewhere unless it has become inaccurate.



##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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

Review Comment:
   The policy says agents cannot open PRs, post comments, or reply to reviewers independently. That's good, but agents could interpret this as permission to do so with a human's general authorization. 
   
   Specify whether an agent may prepare a draft PR or commit locally, and whether a human must personally execute all external publishing actions. I think that the intention was, that we have a human in the loop here and are not letting AI chat with AI all day long, right?



##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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;

Review Comment:
   I would require agents to report precisely which commands ran, which failed, and which checks were not performed. Never claim that unexecuted checks passed since the document doesn't tell agents what to do when dependencies cannot be downloaded, tests are flaky, or the evaluation build is unavailable.
   
   Perhaps it would also make sense to link the EVAL dataset, so agents can actually retrieve it to run eval builds locally.



##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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

Review Comment:
   This is more prescriptive than ASF guidance. The current [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) recommends identifying the tooling used, giving Generated-by and Co-authored-by as examples. It does not mandate the exact trailer format in this document.
   
   If we want to do this, I would explicitly call this an OpenNLP project requirement rather than implying the ASF mandates that exact form.



##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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

Review Comment:
   "Do not allocate in hot loops", "No em dashes", and "A second copy of a helper is a bug" are understandable intentions, but they are more absolute than necessary.
   I would define scope and exceptions to prevent unnecessary refactoring or awkward solutions.
   
   Maybe sth like:
   
   ```
   --- a/AGENTS.md
   +++ b/AGENTS.md
   @@
    - 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.
   +  package you work in. Do not duplicate existing functionality unless there
   +  is a clear technical reason.
   @@
   -- Name repeated literals as constants. Do not allocate in hot loops.
   +- Name repeated literals as constants. Avoid unnecessary allocations in
   +  performance-critical loops.
   @@
   -- No em dashes.
   +- Avoid em dashes in new or modified Javadoc, comments and documentation.
   +  Do not change unrelated text solely to remove them.
   ```



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4247706454


##########
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 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 disucssion and approval

Review Comment:
   Fixed.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4365520472


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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

Review Comment:
   Done



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4365503680


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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

Review Comment:
   It now says the ASF recommends naming the tool and that this trailer form is our project's choice.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "rzo1 (via GitHub)" <gi...@apache.org>.
rzo1 commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6111915093

   "We agreed to follow the lucene standard too and had some standards in the email mentioned- totally agree."
   
   AFAIR we talked about it on the dev@ list but there was no vote nor consensus found yet ;-)


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6124869062

   Also - I kept the removal of the lucene ref (ASF is mentioned though).  No need to have it in AGENTS.md - it will confuse the LLMs when there's contradictions multiple versions etc...  I'll continue our DEV thread.


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "rzo1 (via GitHub) via commits" <co...@opennlp.apache.org>.
rzo1 merged PR #1470:
URL: https://github.com/apache/opennlp/pull/1470


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6160103472

   Agree this should wait on dev@. I'll nudge dev again for consensus. Added the trailer form with an example and noted GitHub only recognizes it with an email. The regex rule now just points to CONTRIBUTING.md so they don't diverge.
   


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
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 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 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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4247701572


##########
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 dev@opennlp.apache.org

Review Comment:
   Fixed both.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4247670678


##########
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).

Review Comment:
   Reworded: a human writes each message; quoted AI output is marked as such and accompanied by the human's comment.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4365513858


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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.
+  The one exception, and the build check that enforces the rule, are described
+  in [CONTRIBUTING.md](.github/CONTRIBUTING.md#regular-expressions-in-production-code).
+- 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

Review Comment:
   Took your wording: public and protected APIs and changed contracts.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6112121959

   > > "We agreed to follow the lucene standard too and had some standards in the email mentioned- totally agree."
   > 
   > AFAIR we talked about it on the dev@ list but there was no vote nor consensus found yet ;-)
   
   Agreed :) It's good we're doing it now because putting something out there is the best way to get the vote out.  I'll make all the changes in a few moments.
   
   But my vote - Version ID of the harness, model/version, and manual sign-off. 


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6115785272

   Thanks, did everything we discussed. 
   
   The file follows the ASF generative tooling guidance as its only policy reference. The disclosure line calls for a `Co-authored-by:` trailer naming the tool, the model and their versions whenever AI contributed to a commit; I chose `Co-authored-by` over `Generated-by` because the human authors, edits and signs off the final change.  The typos and the duplicate JDK bullet are fixed, and "when in doubt" points to GitHub Discussions or dev@. 
   
   Tomorrow (or tonight) I'll start a [DISCUSS] thread on dev@ so the list can settle the wording.


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4365515463


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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;

Review Comment:
   Added a line on reporting what ran, failed or was skipped, and a link to opennlp-data.zip for local eval runs.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4365511442


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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

Review Comment:
   Reworded. 
   
   I went with local edits and commits are fine.  Anything others that people see (push, PR, issue, comment) needs the person’s explicit approval, and what’s posted is their own words with AI text quoted. The rest is in the ASF guidance, which the section now links and summarizes.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#issuecomment-6111900976

   > Hi @krickert - thanks, good to have this. One point should be aligned before merging: the AI disclosure rules need to follow the ASF guidance.
   > 
   > * The [ASF generative tooling guidance](https://www.apache.org/legal/generative-tooling.html) recommends a `Generated-by: <Name of Tool> <Version>` token in the commit message, and the [RAI commit-message practice](https://rai.apache.org/commit-messages.html) asks to name the actual tool and model rather than a generic label. The current "Do not add model identifiers" and the `Assisted-by:` trailer contradict both. Suggested wording:
   >   > Disclose AI help in the commit message with a `Generated-by: <tool> <version>` trailer, naming the actual tool and model version, as recommended by the ASF generative tooling guidance.
   > * Please reference the ASF page as the primary policy; the Lucene AI policy can stay as an additional reference.
   > * Minor: "disucssion" → "discussion"; "enforce the user to post to discussions on GITHUB" → "ask on GitHub Discussions or [dev@opennlp.apache.org](mailto:dev@opennlp.apache.org)"; "Standard JDK character and space tools are usually rewritten in OpenNLP" duplicates the following two bullets and can be removed.
   > 
   > WDYT?
   
   I agree to show the tool, the version of the model and version of the harness.  We agreed to follow the lucene standard too and had some standards in the email mentioned- totally agree.
   
   For the most part (pardon my french) "don't be a jerk" is the overall arching theme - but since it's an LLM, that's pretty subjective.  I think all of the suggestions are spot-on - it's such an important piece that I expect a couple rounds of discussion on this one.
   
   I'm more of an AB test sorta guy, given the uncertainty of LLMs, I think whatever our first version is we'll find tweaks we need to do all the time.  A year from now let's hope the code produced never looks mean to us humans.
   
   When I first used AI, I used to say "it must compile before I look at it" or "look at the source code instead of stack overflow" - that is no longer needed.


-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4247605657


##########
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

Review Comment:
   Added a short Layout section.



-- 
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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4247730538


##########
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 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 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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-1453: Add AGENTS.md with rules for AI coding agents (opennlp)

Posted by "krickert (via GitHub)" <gi...@apache.org>.
krickert commented on code in PR #1470:
URL: https://github.com/apache/opennlp/pull/1470#discussion_r4313161676


##########
AGENTS.md:
##########
@@ -0,0 +1,116 @@
+<!--
+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).
+  Use the form `Co-authored-by: <tool> <version> (<model> <version>) <email>`,
+  for example
+  `Co-authored-by: ExampleCoder 2.1.0 (example-model 4.5) <co...@example.com>`.
+  GitHub only recognizes the trailer with an e-mail address.
+  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

Review Comment:
   I'll clarify it more - but for accessibility reasons I think it's ok if an Agent does on a human behalf as long as the text is from the human (not a summary of) or a quoted translation.  I think agents posting the commands are not something we can prove anyway - but making a highlight to prevent agent-to-agent talk without a human is the point is a good guildeline.  I didn't mention it here though because I didn't want to over complicate it.   I'll add a bullet or two to further clarify 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: commits-unsubscribe@opennlp.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org