|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## What This Is |
| 6 | + |
| 7 | +A collection of standalone Infinispan tutorials organized as a multi-module Maven project. Each tutorial is an independent module demonstrating a specific Infinispan feature. Current version: 16.2.0-SNAPSHOT, targeting Java 17+. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Build all tutorials |
| 13 | +./mvnw clean package |
| 14 | + |
| 15 | +# Build and run tests |
| 16 | +./mvnw clean install |
| 17 | + |
| 18 | +# Build a single tutorial |
| 19 | +./mvnw clean package -pl infinispan-remote/cache |
| 20 | + |
| 21 | +# Run a single tutorial's tests |
| 22 | +./mvnw test -pl infinispan-remote/cache |
| 23 | + |
| 24 | +# Check code formatting |
| 25 | +./mvnw spotless:check |
| 26 | + |
| 27 | +# Fix code formatting |
| 28 | +./mvnw spotless:apply |
| 29 | + |
| 30 | +# Build guides documentation (requires -Pguides profile) |
| 31 | +./mvnw -Pguides -pl docs-maven-plugin package -DskipTests |
| 32 | + |
| 33 | +# Deploy guides locally to infinispan.github.io checkout |
| 34 | +./deploy-guides-local.sh [tutorials-dir] [website-dir] |
| 35 | +``` |
| 36 | + |
| 37 | +## Code Formatting |
| 38 | + |
| 39 | +Enforced by Spotless Maven plugin during `verify` phase: |
| 40 | +- **Java**: 3-space indentation, import order: static, java, javax, org, com, then everything else |
| 41 | +- **XML**: 4-space indentation |
| 42 | +- **YAML**: 2-space indentation |
| 43 | + |
| 44 | +See `.editorconfig` for full details. |
| 45 | + |
| 46 | +## Architecture |
| 47 | + |
| 48 | +### Module Categories |
| 49 | + |
| 50 | +- **`infinispan-remote/`** -- Tutorials using Hot Rod client to connect to an Infinispan Server (client-server mode) |
| 51 | +- **`infinispan-embedded/`** -- Tutorials embedding Infinispan as a library (no server needed) |
| 52 | +- **`integrations/`** -- Tutorials for Spring Boot, Quarkus, and Hibernate integrations |
| 53 | +- **`infinispan-ai/`** -- AI/vector search tutorials (LangChain4j, vector search) |
| 54 | +- **`non-java-clients/`** -- C++, C#, JavaScript Hot Rod client examples |
| 55 | + |
| 56 | +### Shared Connection Helper |
| 57 | + |
| 58 | +`infinispan-remote/connect-to-infinispan-server` is a shared module depended on by most remote tutorials. It provides `TutorialsConnectorHelper` which: |
| 59 | +1. Tries to connect to a running Infinispan Server at `localhost:11222` (user: `admin`, password: `password`) |
| 60 | +2. Falls back to starting a Testcontainers Infinispan instance if no server is found |
| 61 | +3. On SNAPSHOT versions, uses `quay.io/infinispan-test/server:main`; on releases, uses the matching release image |
| 62 | + |
| 63 | +### Tutorial Module Pattern |
| 64 | + |
| 65 | +Each tutorial module follows the same structure: |
| 66 | +- `src/main/java/` -- Runnable main class demonstrating the feature |
| 67 | +- `src/test/java/` -- JUnit 5 test that exercises the same feature |
| 68 | +- `pom.xml` -- Inherits from root, declares `exec-maven-plugin` for `mvn exec:exec` |
| 69 | +- `guide.adoc` (optional) -- AsciiDoc tutorial guide published to infinispan.org |
| 70 | +- Do NOT use em dashes (—) in content. Use regular dashes or rewrite the sentence instead. |
| 71 | + |
| 72 | +### Documentation |
| 73 | + |
| 74 | +- `documentation/asciidoc/` -- AsciiDoc source for published tutorial docs |
| 75 | +- `docs-maven-plugin/` -- Custom Maven plugin that processes `guide.adoc` files from each tutorial into the website format |
| 76 | +- Guides are built with the `guides` Maven profile |
| 77 | + |
| 78 | +## CI |
| 79 | + |
| 80 | +GitHub Actions runs on pushes and PRs to `main`, `development`, and `16.0.x` branches. The CI starts an Infinispan Server container (image varies by branch), then runs `./mvnw -B clean install`. |
| 81 | + |
| 82 | +## Branch Strategy |
| 83 | + |
| 84 | +- `development` -- uses latest Infinispan dev version (`quay.io/infinispan-test/server:main`) |
| 85 | +- `main` -- uses latest stable Infinispan release |
| 86 | +- All contributions target `main` |
0 commit comments