From 60ddc6564bad0132c90c80719706bffacb5b0675 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 4 Feb 2026 14:43:50 +0100 Subject: [PATCH 01/15] First version draft --- AGENTS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..60b3a71e94c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,55 @@ + +# AGENTS.md for Apache Solr + +While README.md and CONTRIBUTING.md are mainly written for humans, this file is a condensed knowledge base for coding agents on the Solr codebase. For background, see https://agents.md + +## Licensing and Dependencies + +- Follow Apache Software Foundation licensing rules, avoid adding a dependency with a banned license +- Always apply the Apache License to new source files +- We use gradle version-catalog toml file to encode dependency versions, never add versions directly to build.gradle files +- We use the "cutterslade-analyze" plugin which requires explicit recording of all dependencies in a build.gradle file +- Always run "gradlew updateLicenses resolveAndLockAll --write-locks" after adding or changing a dependency. See dev-docs/gradle-help/dependencies.txt for more info + +## Build and Development Workflow + +- Always run "gradlew tidy" after editing files +- Always run "gradlew check -x test" before declaring a feature done +- Respect our .editorconfig + +## Code Quality and Best Practices + +- Use the project's custom EnvUtils to read system properties. It auto converts env.var SOLR_FOO_BAR to system property solr.foo.bar +- If you add slf4j log calls, make sure to wrap in logger.isXxxEnabled() clause. Be careful to not add unnecessary logging +- Validate user input. For file paths, always call myCoreContainer.assertPathAllowed(myPath) before using + +## Testing + +- When adding new unit tests, avoid using the old TestHarness and consider using EmbeddedSolrServerTestRule +- See dev-docs/gradle-help/tests.txt for hints on running tests + +## Documentation + +- For major or breaking changes, add a prominent note in reference guide major-changes-in-solr-X.adoc +- Always consider whether a reference-guide page needs updating due to the new/changed features. Target audience is end user +- For changes to build system and other developer-focused changes, consider updating or adding docs in dev-docs/ folder +- Keep all documentation including javadoc concise + +## Changelog + +- We use logchange as changelog tool. Add a new file changelog/unreleased/describe-your-feature.yml for each change, see dev-docs/changelog.adoc From 99087810a82d02ab520e3438f028ff60b990c2e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Thu, 5 Feb 2026 12:49:35 +0100 Subject: [PATCH 02/15] More precise tidy instruction Co-authored-by: David Smiley --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 60b3a71e94c..0ce7df61a1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Build and Development Workflow -- Always run "gradlew tidy" after editing files +- When done or preparing to commit changes to java source files, be sure to run `gradlew tidy` to format the code - Always run "gradlew check -x test" before declaring a feature done - Respect our .editorconfig From efab8a6f0a2f149408532f062c7422b5ded2c51b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Thu, 5 Feb 2026 12:58:26 +0100 Subject: [PATCH 03/15] add javadocs, do not add comment to mention the change Co-authored-by: David Smiley --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0ce7df61a1c..4a5100243b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,8 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - Always consider whether a reference-guide page needs updating due to the new/changed features. Target audience is end user - For changes to build system and other developer-focused changes, consider updating or adding docs in dev-docs/ folder - Keep all documentation including javadoc concise +- New classes should have some javadocs +- Changes should not have code comments communicating the change, which are instead great comments to leave for code review / commentary ## Changelog From 773f1337348439244c0698efb0df5f7c40c30290 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Thu, 5 Feb 2026 13:00:13 +0100 Subject: [PATCH 04/15] how to create tests, what to avoid Co-authored-by: David Smiley --- AGENTS.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4a5100243b8..1aa76a2c174 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,12 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Testing -- When adding new unit tests, avoid using the old TestHarness and consider using EmbeddedSolrServerTestRule +- When adding a test to an existing suite/file, keep the same style / design choices +- When adding a *new* Java test suite/file: + - Subclass SolrTestCase, or if SolrCloud is needed then SolrCloudTestCase + - If SolrTestCase and need to embed Solr, use either EmbeddedSolrServerTestRule (doesn't use HTTP) or SolrJettyTestRule if HTTP/Jetty is relevant to what is being tested. + - Avoid SolrTestCaseJ4 for new tests + - See dev-docs/gradle-help/tests.txt for hints on running tests ## Documentation From 00f063a7798f850c7e32548fa6848199e57bfc34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 01:21:15 +0100 Subject: [PATCH 05/15] Link to gradle/libs.versions.toml Mention how to treat a bom --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1aa76a2c174..e00d72e962e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,8 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - Follow Apache Software Foundation licensing rules, avoid adding a dependency with a banned license - Always apply the Apache License to new source files -- We use gradle version-catalog toml file to encode dependency versions, never add versions directly to build.gradle files +- We use gradle version-catalog (gradle/libs.versions.toml) to encode dependency versions, never add versions directly to build.gradle files +- If a dependency is covered by a bom, declare "empty" version-less dependencies for individual libraries. - We use the "cutterslade-analyze" plugin which requires explicit recording of all dependencies in a build.gradle file - Always run "gradlew updateLicenses resolveAndLockAll --write-locks" after adding or changing a dependency. See dev-docs/gradle-help/dependencies.txt for more info @@ -45,7 +46,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - Subclass SolrTestCase, or if SolrCloud is needed then SolrCloudTestCase - If SolrTestCase and need to embed Solr, use either EmbeddedSolrServerTestRule (doesn't use HTTP) or SolrJettyTestRule if HTTP/Jetty is relevant to what is being tested. - Avoid SolrTestCaseJ4 for new tests - + - See dev-docs/gradle-help/tests.txt for hints on running tests ## Documentation From 1b3562041de11f58e2eee370144b39537e6a5f74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 01:29:14 +0100 Subject: [PATCH 06/15] Rename plugin mention from cutterslade to gradle-dependency-analyze Tell it not to use the permit* keywords often --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e00d72e962e..9827e2267ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - Always apply the Apache License to new source files - We use gradle version-catalog (gradle/libs.versions.toml) to encode dependency versions, never add versions directly to build.gradle files - If a dependency is covered by a bom, declare "empty" version-less dependencies for individual libraries. -- We use the "cutterslade-analyze" plugin which requires explicit recording of all dependencies in a build.gradle file +- We use the "gradle-dependency-analyze" plugin, which requires explicit recording of all dependencies in a build.gradle file. Only in very rare cases use the 'permitUnusedDeclared' and other 'permit*' options. - Always run "gradlew updateLicenses resolveAndLockAll --write-locks" after adding or changing a dependency. See dev-docs/gradle-help/dependencies.txt for more info ## Build and Development Workflow From 0c3a282afb38e0b18a83a19b4d539aa94f22273b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 01:31:25 +0100 Subject: [PATCH 07/15] slf4j --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9827e2267ee..5395d8385ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Code Quality and Best Practices - Use the project's custom EnvUtils to read system properties. It auto converts env.var SOLR_FOO_BAR to system property solr.foo.bar -- If you add slf4j log calls, make sure to wrap in logger.isXxxEnabled() clause. Be careful to not add unnecessary logging +- Be careful to not add non-essential logging! If you add slf4j log calls, make sure to wrap debug/trace level calls in logger.isXxxEnabled() clause - Validate user input. For file paths, always call myCoreContainer.assertPathAllowed(myPath) before using ## Testing From 54827560a8290b040a0d699612f86576b39316d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 01:34:15 +0100 Subject: [PATCH 08/15] Changelog --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5395d8385ce..08c786f9993 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,4 +60,6 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Changelog -- We use logchange as changelog tool. Add a new file changelog/unreleased/describe-your-feature.yml for each change, see dev-docs/changelog.adoc +- We use logchange (https://logchange.dev/tools/logchange/) as changelog tool, each change is represented by one yaml file each in changelog/unreleased +- Read dev-docs/changelog.adoc for our changelog conventions and how to scaffold a new file +- Do not add a changelog before you know either a JIRA issue number or a github number, as one is required. From fd1857652e4348b3e8acdf366c0f50b047b1813f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 01:42:58 +0100 Subject: [PATCH 09/15] Update how-to-contribute.adoc --- dev-docs/how-to-contribute.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dev-docs/how-to-contribute.adoc b/dev-docs/how-to-contribute.adoc index fdd60619d28..4ff6edeaae5 100644 --- a/dev-docs/how-to-contribute.adoc +++ b/dev-docs/how-to-contribute.adoc @@ -64,8 +64,9 @@ In order to make a new contribution to Solr you will use the fork you have creat ## Use of AI Coding Assistants -AI-powered tools (like GitHub Copilot, ChatGPT, etc.) can assist with contributions, but human contributors remain fully responsible for all submitted code and documentation. See the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) for the foundation's policy. If you use AI tools: +AI-powered tools or agents (like GitHub Copilot, ChatGPT, etc.) can assist with contributions, but human contributors remain fully responsible for all submitted code and documentation. See the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) for the foundation's policy. If you use AI tools: +- Do include our `AGENTS.md` file in the LLM's context for best result. - Carefully review all generated content for correctness, security, and alignment with Solr's architecture - For major AI-assisted contributions, disclose the use of AI tools in your PR description - For documentation contributions, prefer concise, human-readable content over verbose AI-generated text From caaedc7384d7adca35b23dd5825148cd14f4712d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 12:41:32 +0100 Subject: [PATCH 10/15] Expand intro text, link to hot-to-contribute --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 08c786f9993..e16305b97af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ --> # AGENTS.md for Apache Solr -While README.md and CONTRIBUTING.md are mainly written for humans, this file is a condensed knowledge base for coding agents on the Solr codebase. For background, see https://agents.md +While README.md and CONTRIBUTING.md are mainly written for humans, this file is a condensed knowledge base for LLM coding agents on the Solr codebase. See https://agents.md for more info and how to make various coding assistants consume this file. Also see dev-docs/how-to-contribute.adoc for some guidelines when using genAI to contribute to Solr. ## Licensing and Dependencies From 3afe3c5fe10a351b6344fcba3f0c3318f8ea9ca1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 22:46:23 +0100 Subject: [PATCH 11/15] Update AGENTS.md Co-authored-by: David Smiley --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e16305b97af..f8a4b9d8fc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - Follow Apache Software Foundation licensing rules, avoid adding a dependency with a banned license - Always apply the Apache License to new source files -- We use gradle version-catalog (gradle/libs.versions.toml) to encode dependency versions, never add versions directly to build.gradle files +- We use gradle version-catalog (gradle/libs.versions.toml) to encode dependency versions; never add versions directly to build.gradle files - If a dependency is covered by a bom, declare "empty" version-less dependencies for individual libraries. - We use the "gradle-dependency-analyze" plugin, which requires explicit recording of all dependencies in a build.gradle file. Only in very rare cases use the 'permitUnusedDeclared' and other 'permit*' options. - Always run "gradlew updateLicenses resolveAndLockAll --write-locks" after adding or changing a dependency. See dev-docs/gradle-help/dependencies.txt for more info From b3af6f6a56010972744d8e62044cb2293880dadf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 22:46:06 +0100 Subject: [PATCH 12/15] Bom --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f8a4b9d8fc5..cb12a8bd765 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - Follow Apache Software Foundation licensing rules, avoid adding a dependency with a banned license - Always apply the Apache License to new source files - We use gradle version-catalog (gradle/libs.versions.toml) to encode dependency versions; never add versions directly to build.gradle files -- If a dependency is covered by a bom, declare "empty" version-less dependencies for individual libraries. +- If a dependency is covered by an existing Bill Of Materials (BOM), try first declaring it without a version - We use the "gradle-dependency-analyze" plugin, which requires explicit recording of all dependencies in a build.gradle file. Only in very rare cases use the 'permitUnusedDeclared' and other 'permit*' options. - Always run "gradlew updateLicenses resolveAndLockAll --write-locks" after adding or changing a dependency. See dev-docs/gradle-help/dependencies.txt for more info From 78942a86437901100596e0dd50d5fbc27761d368 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 22:49:46 +0100 Subject: [PATCH 13/15] Changelog --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cb12a8bd765..e4b36b6a517 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,6 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Changelog -- We use logchange (https://logchange.dev/tools/logchange/) as changelog tool, each change is represented by one yaml file each in changelog/unreleased -- Read dev-docs/changelog.adoc for our changelog conventions and how to scaffold a new file -- Do not add a changelog before you know either a JIRA issue number or a github number, as one is required. +- We use the "logchange" tooling to manage our changelog. See dev-docs/changelog.adoc for details and conventions +- To scaffold a new changelog entry, run "gradlew writeChangelog", and then edit the generated file +- Do not add a changelog file before a JIRA issue or a github PR is assigned, as one is required. From b0cf2f931415edc041891994257740d12c7b54e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Fri, 6 Feb 2026 22:57:50 +0100 Subject: [PATCH 14/15] Rephrase changelog --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e4b36b6a517..8b533b08250 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,5 +61,5 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Changelog - We use the "logchange" tooling to manage our changelog. See dev-docs/changelog.adoc for details and conventions -- To scaffold a new changelog entry, run "gradlew writeChangelog", and then edit the generated file -- Do not add a changelog file before a JIRA issue or a github PR is assigned, as one is required. +- To scaffold a new changelog entry, run "gradlew writeChangelog", and then edit the new file located in "changelog/unreleased/". +- Do not add a changelog entry before a JIRA issue or a Github PR is assigned, as one is required. From a1bf67b47f54f4105318f5ac5abaca1edf24d6a7 Mon Sep 17 00:00:00 2001 From: David Smiley Date: Fri, 6 Feb 2026 22:26:28 -0500 Subject: [PATCH 15/15] minor improvements. back-tick quoting files, commands, and code. --- AGENTS.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8b533b08250..4395a2a4ee5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,28 +16,27 @@ --> # AGENTS.md for Apache Solr -While README.md and CONTRIBUTING.md are mainly written for humans, this file is a condensed knowledge base for LLM coding agents on the Solr codebase. See https://agents.md for more info and how to make various coding assistants consume this file. Also see dev-docs/how-to-contribute.adoc for some guidelines when using genAI to contribute to Solr. +While README.md and CONTRIBUTING.md are mainly written for humans, this file is a condensed knowledge base for LLM coding agents on the Solr codebase. See https://agents.md for more info and how to make various coding assistants consume this file. Also see `dev-docs/how-to-contribute.adoc` for some guidelines when using genAI to contribute to Solr. ## Licensing and Dependencies - Follow Apache Software Foundation licensing rules, avoid adding a dependency with a banned license - Always apply the Apache License to new source files -- We use gradle version-catalog (gradle/libs.versions.toml) to encode dependency versions; never add versions directly to build.gradle files -- If a dependency is covered by an existing Bill Of Materials (BOM), try first declaring it without a version -- We use the "gradle-dependency-analyze" plugin, which requires explicit recording of all dependencies in a build.gradle file. Only in very rare cases use the 'permitUnusedDeclared' and other 'permit*' options. -- Always run "gradlew updateLicenses resolveAndLockAll --write-locks" after adding or changing a dependency. See dev-docs/gradle-help/dependencies.txt for more info +- All versions must be delcared in `gradle/libs.versions.toml`, never build.gradle files +- Try first declaring a dependency without a version (the version might already be in a BOM); and if fails to resolve _then_ specify a version +- The build may complain with "Dependency analysis found issues.", a category like "usedUndeclaredArtifacts", and a dependency list. Declare or undeclare these dependencies, as the category will imply. The special 'permit*' configurations are a choice of last resort. +- Always run `gradlew updateLicenses resolveAndLockAll --write-locks` after adding or changing a dependency. See `dev-docs/gradle-help/dependencies.txt` for more info ## Build and Development Workflow - When done or preparing to commit changes to java source files, be sure to run `gradlew tidy` to format the code -- Always run "gradlew check -x test" before declaring a feature done -- Respect our .editorconfig +- Always run `gradlew check -x test` before declaring a feature done ## Code Quality and Best Practices -- Use the project's custom EnvUtils to read system properties. It auto converts env.var SOLR_FOO_BAR to system property solr.foo.bar -- Be careful to not add non-essential logging! If you add slf4j log calls, make sure to wrap debug/trace level calls in logger.isXxxEnabled() clause -- Validate user input. For file paths, always call myCoreContainer.assertPathAllowed(myPath) before using +- Use the project's custom `EnvUtils` to read system properties. It auto converts env.var SOLR_FOO_BAR to system property solr.foo.bar +- Be careful to not add non-essential logging! If you add slf4j log calls, make sure to wrap debug/trace level calls in `logger.isXxxEnabled()` clause +- Validate user input. For file paths, always call `myCoreContainer.assertPathAllowed(myPath)` before using ## Testing @@ -47,7 +46,7 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is - If SolrTestCase and need to embed Solr, use either EmbeddedSolrServerTestRule (doesn't use HTTP) or SolrJettyTestRule if HTTP/Jetty is relevant to what is being tested. - Avoid SolrTestCaseJ4 for new tests -- See dev-docs/gradle-help/tests.txt for hints on running tests +- See `dev-docs/gradle-help/tests.txt` for hints on running tests ## Documentation @@ -60,6 +59,6 @@ While README.md and CONTRIBUTING.md are mainly written for humans, this file is ## Changelog -- We use the "logchange" tooling to manage our changelog. See dev-docs/changelog.adoc for details and conventions -- To scaffold a new changelog entry, run "gradlew writeChangelog", and then edit the new file located in "changelog/unreleased/". +- We use the "logchange" tooling to manage our changelog. See `dev-docs/changelog.adoc` for details and conventions +- To scaffold a new changelog entry, run `gradlew writeChangelog`, and then edit the new file located in `changelog/unreleased/`. - Do not add a changelog entry before a JIRA issue or a Github PR is assigned, as one is required.