janhoy commented on code in PR #5323: URL: https://github.com/apache/solr/pull/5323#discussion_r4562010168
########## solr/packaging/README.md: ########## @@ -0,0 +1,82 @@ +<!-- + 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. +--> + +# solr/packaging + +Assembles the Solr binary distribution, and hosts the tests that drive `bin/solr` and `bin\solr.cmd` — they need an unpacked distribution, which is why they live here. + +No production Java of its own. `README.txt` in this directory ships *inside* the distribution and is not developer documentation. + +## Building a distribution + +| Task | Output | +| --- | --- | +| `installFullDist` / `installSlimDist` | `build/solr-<version>` / `build/solr-<version>-slim` | +| `fullDistTar` / `slimDistTar` | `build/distributions/solr-<version>[-slim].tgz` | +| `devFull` / `devSlim` / `dev` | a copy at `build/dev` / `build/dev-slim`, for working by hand | + +Slim is `bin`, `server`, `docker`, `lib` and licenses; full adds `example`, `modules` and `cross-dc-manager`. Zip variants are disabled. `assembleDist` also requires `-Psolr.ui.buildFromSource=true`, so a release never pulls the Admin UI from nightlies. + +```bash +./gradlew -p solr/packaging devSlim +cd solr/packaging/build/dev-slim && bin/solr start -f +``` + +The test tasks use `build/solr-<version>`, so a `dev` directory you are poking at is never disturbed by a test run. + +## Tests + +| Layer | Task | Status | +| --- | --- | --- | +| CATS (JUnit, cross-platform) | `catsTests`, `catsTestsPicocli`, `catsTestsCommonsCli` | preferred | +| Rolling upgrade (Docker) | `catsTestsDockerBuild` | builds the image first, so it has its own task | +| Everything, in parallel | `catsTestsAll` | the above in one fork pool; builds the image too | +| BATS suites (bash) | `integrationTests`, `integrationTestsPicocli` | deprecated, being ported to CATS | +| Stock `test` | — | disabled here | + +The real layers all start Solr nodes and take minutes, so none of them is in `check`; ask for them by name. The `*CommonsCli` and `*Picocli` variants pin `SOLR_PICOCLI`, since the two CLI implementations still differ in some wording. + +**CATS** — Cross-platform Automated Testing System. JUnit suites in `src/test/org/apache/solr/shell/` extending `SolrShellTestCase`. One test source runs against `bin/solr` under bash and `bin\solr.cmd` under cmd.exe. Each test class gets its own `SOLR_HOME`, `SOLR_PID_DIR` and port block, so classes run in parallel forks (`min(4, tests.jvms)`, override with `-Pcats.tests.jvms`). See [`solr/test-framework/README.md`](../test-framework/README.md) for the API. + +```bash +./gradlew -p solr/packaging catsTests --tests "*ZkTest" +``` + +`RollingUpgradeTest` upgrades a three-node cluster from the previous major's released image to one built from your working tree, so it needs that image and runs only from `catsTestsDockerBuild` or `catsTestsAll`. Prefer `catsTestsAll` when you want the whole suite: tasks within a project run sequentially, so asking for both of the others runs the upgrade after everything else instead of alongside it. `ExtractionTest` also wants Docker, pulling a Tika server image rather than building one, and skips when the daemon or the image is unavailable. Nothing else triggers a Docker build — not `catsTests`, not `check` — and the task tags the image under a local-only name, so an `apache/solr:<version>` you pulled from Docker Hub is never overwritten. Review Comment: I'm constantly fighting my LLM to have him dial down on the documentation volume - think AGENTS.md could perhaps do a better job here at constraining docs and code-comments. Maybe even a `.agents/skills/solr-documentation/SKILL.md` that could be used by humans and LLMs alike -- which nails down all our documentation preferences and rules, linked from AGENTS.md? Agree this can be 2 lines.. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
