Here's a first draft for PR review. <ttps://github.com/apache/opennlp/blob/feat/GH-1453-agents-md/AGENTS.md>
I researched guidelines from Claude, OpenAI, and Msft. I also drew from other projects (including Lucene). I minimized the file because it is intended for machines. Using brief bullet points minimizes tokens while keeping a human voice so that both people and machines can understand it. I only kept a reference to the ASF's policy because too many attributions consume tokens and can quickly cause drift and confusion for the machines. Here's the PR <https://github.com/apache/opennlp/pull/1470> Here's the issue <https://github.com/apache/opennlp/issues/1453> Thanks for the opportunity to give this a first shot - LMK what you think! Encourage the comments in the PR (but anywhere is fine, I'll track them). Keep in mind that given the rate of progress in this area, we'll likely change this regularly. Rungs, Kristian On Tue, Oct 6, 2026 at 1:18 AM Martin Wiesner <[email protected]> wrote: > Hi Kristian, > > quick follow-up on you question: If you can provide a separate Issue / PR > for adding AGENTS.md the project and its community / ecosystem will be > happy. > > In any case: Don’t overengineer it, put focus on essentials and quality > for a first drop of it in 3.0.0. > > Lkn fwd. > > Best > Martin > > > Am 22.09.2026 um 21:02 schrieb Kristian Rickert <[email protected]>: > > > > It's become standard to have AGENTS.md in an open source project serve as > > the "README for agents". > > > > When we release 3.0, we should have one. > > > > Since we were on that subject - anyone object? > > > > > > On Tue, Sep 22, 2026 at 1:11 PM Richard Zowalla <[email protected]> wrote: > > > >> Hi all, > >> > >> thanks for the feedback so far. I'd like to follow up on two points. > >> > >> 1.) Stacked PRs > >> > >> My "no stacking" in B was too strict as written. I'm fine with stacked > PRs > >> if they're a deliberate way to break a larger issue into manageable > pieces. > >> What I object to is stacks where nobody can tell anymore what a single > PR > >> is about. So I'd rephrase B roughly as: > >> > >> Each PR in a stack has a concise, self-contained intent and its own > issue. > >> The initial description is clear to a human reviewer: it says that the > PR > >> is part of a stack, what it depends on, and what it adds on top. > >> The stack stays stable. No new scope while it's under review, and > parents > >> get reviewed and merged first. > >> If a reviewer has to dig through the whole stack to understand one PR, > it > >> has to be broken down differently. > >> > >> 2.) GitHub Discussions > >> > >> GitHub Discussions can be a useful additional channel, similar to users@ > , > >> but it can't and shouldn't replace the mailing list. Mailing lists are a > >> core value of the ASF. They're independent of any single vendor, they > work > >> asynchronously across time zones, they're accessible to everyone, and > >> they're archived for the long term. dev@ remains the primary place for > >> technical discussions and the sole authority for decisions. > >> > >> It's fine to gather additional feedback in a GitHub discussion or a > GitHub > >> issue. But the outcome has to be brought back to the list, and any > decision > >> is made here. Or, strictly ASF speaking: if it didn't happen on the > list, > >> it didn't happen. > >> > >> 3.) Lucene AI policy > >> > >> I've read the Lucene AI policy and I think it's fine, and a good basis > for > >> us too. My main concern is simple: I don't want to talk with an AI. > When I > >> review a PR or reply to a comment, I want to know that there's a human > on > >> the other side who understands the change and stands behind it. That's > the > >> core value for me, and the Lucene policy covers it well. Open source is > >> about collaboration between people, and tools don't change that. > >> > >> Gruß > >> Richard > >> > >> > >>> Am 22.09.2026 um 18:07 schrieb Kristian Rickert <[email protected]>: > >>> > >>> Sounds good. Agree on most but the stacks... > >>> > >>> - *Hand written guideline tutorial - *I'd volunteer to write up a good > >>> sorta "tutorial" that goes over "dos" and "do nots" of how you should > >> push > >>> a PR. > >>> - *I disagree with not having stacks for complex features, but try to > >>> minimize the noise and rebase* -Stacks are normal in open source > >>> projects for larger features. I think anything on a downstream stack > >>> should remain in draft. Github even has a stack feature now. That > >> being > >>> said, I'm fine with not doing a stack because it's not hard to have it > >>> otherwise. > >>> - *Drafts are OK if they start *green but are later converted to > draft. > >>> Otherwise the work should be on a collaboration branch without being > in > >>> draft. * Please let's view drafts as not reviewable* - as the button > to > >>> turn green says "ready for review?" will get users regularly confused > >> about > >>> the deviation on github. > >>> - *Limit PRs open - *Unless the team agrees on the number of PRs (i.e. > >>> the anti-regex push), we should try to limit the amount. I promised > >> that > >>> after the current stack is done, I'll limit my PRs to 0-2 with a > >> primary > >>> focus on bug fixing, backporting, and features to be done > >> collaboratively/ > >>> discussed on. > >>> - *Discussions on github - *I hope we can bring more discussions to > >>> github - as design and collaboration have a lot of features you don't > >> get > >>> in email (i.e. mermaid arch diagrams). > >>> > >>> > >>> Thanks for bringing it to the thread. > >>> > >>> > >>> > >>> > >>> On Thu, Sep 17, 2026 at 9:07 AM Jeff Zemerick <[email protected]> > >> wrote: > >>> > >>>> Good points. I agree with putting all of these points in the > >>>> contributor guidelines, and I especially like the expectations for > >>>> committers in the last section. Ultimately, any policy affects the > >>>> committers the most. > >>>> > >>>> It's reassuring to see that OpenNLP is not the only ASF (and I'm sure > >>>> non-ASF) project adapting to the new ways of working. Lucene has > >>>> recently adopted an AI Policy [1] over using AI-generated responses > >>>> for communication. I would favor the same or a similar policy for > >>>> OpenNLP, too. While I don't think OpenNLP is facing this issue to the > >>>> degree Lucene is, I think it would be good to go ahead and get a > >>>> policy in place becase it's probably only a matter of time until > >>>> OpenNLP is. > >>>> > >>>> Thanks, > >>>> Jeff > >>>> > >>>> [1] https://github.com/apache/lucene/blob/main/AI_POLICY.md > >>>> > >>>> On Thu, Sep 17, 2026 at 5:53 AM Richard Zowalla <[email protected]> > >> wrote: > >>>>> > >>>>> Hi all, > >>>>> > >>>>> Over the last few weeks the number and size of open pull requests has > >>>> grown far beyond what we can review, and I think we all share part of > >> the > >>>> blame. > >>>>> > >>>>> So I'd like to agree on a few practices for everyone, contributors > and > >>>> committers alike. > >>>>> > >>>>> 1.) Why this matters > >>>>> > >>>>> Every change we merge has to be read and understood by a human > >>>> committer, who then takes responsibility for it. That's how Apache > >> works, > >>>> and a green build or a machine-generated review doesn't replace it. > I'm > >>>> including myself here: I've posted LLM-generated reviews on some PRs > >> when I > >>>> was short on time. They can help, but they aren't a review, and we > >>>> shouldn't pretend they are. > >>>>> > >>>>> This has also become a problem for the community itself. Some people > >>>> have told me privately that they can't handle the review load anymore, > >> and > >>>> some have stopped reviewing completely. That's the worst outcome for a > >>>> volunteer project. Reviewers are our scarcest resource, and if we burn > >> them > >>>> out, nothing gets merged, no matter how good the code is. I don't want > >>>> anyone to feel they have to step back because the queue has become > >>>> impossible to keep up with. > >>>>> > >>>>> Right now there are about 24 open PRs [1] adding about 246k lines. > Much > >>>> of that code is duplicated across PRs, and nobody can tell which part > >> of a > >>>> diff belongs to which change; description or comments are outdated > and a > >>>> human is totally lost. Some examples, only to show the pattern: > >>>>> > >>>>> - Stacked PRs that all target main repeat their parents' diffs: > #1213, > >>>> #1214 and #1215 each contain all of #1152 (+30k to +40k lines, 138–165 > >>>> commits each) [2], and #1276–#1282 all contain #1275 [3]. > >>>>> - The same code is in several PRs at once (the TextEmbedder SPI is in > >>>> #1290 and #1152) [4], so review comments on one copy never reach the > >> others. > >>>>> - Descriptions no longer match the diff, for example PRs that list > >>>> dependencies which were merged long ago, or file counts and scope that > >> have > >>>> since changed [5]. Several of us have left comments saying we simply > >> don't > >>>> understand what a PR is about. > >>>>> - Some PRs have 100+ commits, including merge commits from main. > >>>>> - New scope gets added to PRs while they are under review, and new > >>>> drafts keep opening before the existing ones are done. > >>>>> > >>>>> None of this says the work is bad. Much of it fixes real bugs and > adds > >>>> useful features. But a PR that a volunteer can't review in one sitting > >>>> doesn't get a real review. > >>>>> It either sits there (forever) or gets merged on trust, and neither > is > >>>> acceptable > >>>>> > >>>>> 2.) Proposal > >>>>> > >>>>> A. One PR, one JIRA, one unit a human can review. > >>>>> > >>>>> Squash to a single commit, or to a few commits that each make sense > on > >>>> their own. Rebase on main instead of merging main in. The title and > >>>> description should say what the PR does *now*: rewrite them when the > >> scope > >>>> changes rather than adding "review round" sections, since the history > is > >>>> already in the comments. > >>>>> > >>>>> B. No stacking. > >>>>> > >>>>> A PR targets main and contains only its own change. If it depends on > >>>> another open PR, it waits on the contributor's fork until that parent > is > >>>> merged. A PR should never show the diff of another open PR. > >>>>> > >>>>> C. Optional modules go to opennlp-addons. > >>>>> > >>>>> New optional modules with their own data, dependencies or follow-up > >>>> plans belong in opennlp-addons [6]. The current embeddings, vector > >> index, > >>>> gazetteer and wordnet drafts are examples [7]. Core only gets the > small > >> API > >>>> contracts those modules really need, each in its own focused PR. > >>>>> > >>>>> D. Finish before starting something new. > >>>>> > >>>>> Limit how many PRs one person has ready for review at a time (3–4, > >> say). > >>>> Don't add new scope to a PR that is under review; put new ideas in > JIRA > >>>> first. > >>>>> The speed at which we can review sets how fast code gets in, not the > >>>> speed at which code gets written. Five finished PRs are worth more to > us > >>>> than 24 open ones. > >>>>> > >>>>> E. Committers, too. > >>>>> > >>>>> We should review in time and reply clearly: approve, request specific > >>>> changes, or say it doesn't fit and close it. We shouldn't post > generated > >>>> reviews as if they were our own. If we use tools, we check and sign > off > >> on > >>>> every point we post. And it's fine to say "this is too big for me to > >>>> review", which is useful feedback, not a failure. > >>>>> > >>>>> > >>>>> If we agree, we should add this to the contribution guidelines and > the > >>>> PR template. > >>>>> For the PRs already open, I suggest we agree on a merge order > together, > >>>> and close or park stacked and duplicated ones until their turn comes. > >>>>> > >>>>> And to those who stepped back: thank you for everything you've > reviewed > >>>> so far. I hope this makes it possible for you to come back. > >>>>> > >>>>> Thoughts? > >>>>> > >>>>> Gruß > >>>>> Richard > >>>>> > >>>>> --- > >>>>> > >>>>> ## References > >>>>> > >>>>> **[1] Open pull requests** > >>>>> - https://github.com/apache/opennlp/pulls > >>>>> > >>>>> **[2] Static embeddings stack** > >>>>> - https://github.com/apache/opennlp/pull/1152 ([OPENNLP-1877]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1877)) > >>>>> - https://github.com/apache/opennlp/pull/1213 ([OPENNLP-1895]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1895)) > >>>>> - https://github.com/apache/opennlp/pull/1214 ([OPENNLP-1910]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1910)) > >>>>> - https://github.com/apache/opennlp/pull/1215 ([OPENNLP-1911]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1911)) > >>>>> > >>>>> **[3] Regex removal** > >>>>> - https://github.com/apache/opennlp/pull/1275 ([OPENNLP-1928]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1928)) > >>>>> - https://github.com/apache/opennlp/pull/1276 ([OPENNLP-1930]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1930)) > >>>>> - https://github.com/apache/opennlp/pull/1277 ([OPENNLP-1931]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1931)) > >>>>> - https://github.com/apache/opennlp/pull/1278 ([OPENNLP-1932]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1932)) > >>>>> - https://github.com/apache/opennlp/pull/1279 ([OPENNLP-1933]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1933)) > >>>>> - https://github.com/apache/opennlp/pull/1280 ([OPENNLP-1929]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1929)) > >>>>> - https://github.com/apache/opennlp/pull/1281 ([OPENNLP-1934]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1934)) > >>>>> - https://github.com/apache/opennlp/pull/1282 ([OPENNLP-1935]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1935)) > >>>>> > >>>>> **[4] TextEmbedder SPI and shared deep-learning encoder tests** > >>>>> - https://github.com/apache/opennlp/pull/1290 ([OPENNLP-1937]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1937)) > >>>>> - https://github.com/apache/opennlp/pull/1288 ([OPENNLP-1942]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1942)) > >>>>> > >>>>> **[5] Dependency parser stack** > >>>>> - https://github.com/apache/opennlp/pull/1236 ([OPENNLP-547]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-547)) > >>>>> - https://github.com/apache/opennlp/pull/1237 ([OPENNLP-1919]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1919)) > >>>>> - https://github.com/apache/opennlp/pull/1238 ([OPENNLP-1920]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1920)) > >>>>> > >>>>> **[6] opennlp-addons, with an example add-on PR** > >>>>> - https://github.com/apache/opennlp-addons > >>>>> - https://github.com/apache/opennlp-addons/pull/184 ([OPENNLP-1885]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1885)) > >>>>> > >>>>> **[7] Drafts that belong in opennlp-addons** > >>>>> - https://github.com/apache/opennlp/pull/1154 ([OPENNLP-1879]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1879)) > >>>>> - https://github.com/apache/opennlp/pull/1155 ([OPENNLP-1880]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1880)) > >>>>> - https://github.com/apache/opennlp/pull/1167 ([OPENNLP-1887]( > >>>> https://issues.apache.org/jira/browse/OPENNLP-1887)) > >>>>> - plus the embeddings stack in [2] > >>>> > >> > >> > >
