From 658ab0e142dfbc8ff10cfe7166ff39661a8a32cc Mon Sep 17 00:00:00 2001 From: Kai Moritz Date: Fri, 22 May 2026 08:26:53 +0000 Subject: [PATCH] =?utf8?q?CLAUDE.md=20f=C3=BCr=20Claude=20Code=20hinzugef?= =?utf8?q?=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..24aaf4a4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,78 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Purpose + +This is a **Kafka training repository** used for teaching Apache Kafka concepts. It uses a branch-per-exercise model where each exercise lives on its own Git branch. The `scripting` branch (current) contains only management scripts — actual exercise code lives on other branches. + +## Branch Structure + +Branches follow a naming convention that encodes their role: + +| Suffix | Meaning | +|--------|---------| +| *(none)* | Solution / Musterlösung | +| `--vorlage` | Exercise template for students to start from | +| `--livecoding` | Live-coding demo starting point | +| `--livecoding--schritte` | Step-by-step increments of a live-coding session | + +Branch name prefixes group exercises by topic: +- `grundlagen/*` — Plain Java Kafka client basics +- `producer/*` — Producer-focused exercises (advanced) +- `consumer/*` — Consumer-focused exercises (advanced) +- `springkafka/*` — Spring Kafka API exercises +- `config/*` — Docker/infrastructure configuration examples + +Each branch variable in `BRANCHES.sh` has a corresponding `__ROOT` variable that defines its rebase parent, forming a directed dependency chain of exercises. + +## Each Exercise Branch + +A typical exercise branch contains: + +- `README.sh` — the canonical way to run the exercise (builds, starts Docker Compose, runs demo) +- `docker/docker-compose.yml` — local Kafka cluster setup +- `pom.xml` and/or `build.gradle` — Maven/Gradle build (Java 21, Spring Boot 4.0.2) +- `src/` — Java source code (group `de.juplo.kafka`) + +Run an exercise: +```bash +git checkout +./README.sh # start and demo +./README.sh build # build only +./README.sh cleanup # tear down Docker, clean build artifacts +``` + +## Scripting Branch Scripts + +All scripts source `BRANCHES.sh` first, which defines the full branch list and parent relationships. + +| Script | Purpose | +|--------|---------| +| `BRANCHES.sh` | Defines all branch names and their `__ROOT` parents | +| `REBASE.sh` | Rebases every branch onto its `__ROOT` parent | +| `BUILD.sh` | Checks out each branch and builds with Maven + pushes Docker image | +| `GRADLE.sh` | Same as BUILD.sh but using Gradle | +| `MAVEN.sh` | `mvn clean install` + `mvn docker:push` for all branches | +| `PUSH.sh` | Force-pushes all branches to origin (creates timestamped backup tags first) | +| `RESET.sh` | Resets all branches to `origin/` or to a tag prefix (`./RESET.sh `) | +| `TAG.sh` | Tags all branches as `--` and pushes tags (`./TAG.sh `) | +| `DIFF.sh` | Diffs every branch against remote (or against a tag suffix if given) | +| `COPY.sh` | Copies branches to `../vorlagen`, `../livecoding`, `../spickzettel` directories | +| `patch_gradle_for_si_nexus.sh` | Patches `build.gradle`/`settings.gradle` to use internal Nexus mirror | + +Always return to `scripting` after bulk operations — scripts `git checkout scripting` at the end. + +## Adding a New Exercise Branch + +1. Add the variable name and value (branch name) to `BRANCHES.sh`. +2. Add the corresponding `__ROOT` variable pointing to the parent branch. +3. Add the variable name to the `BRANCHES` list inside `BRANCHES.sh`. +4. Run `./REBASE.sh` to verify the chain is consistent. +5. Run `./PUSH.sh` to publish. + +## Key Constraints + +- `PUSH.sh` force-pushes — it is intentional and expected for this training workflow. +- `--vorlage` branches are skipped by build scripts (they are incomplete by design). +- The `grundlagen/docker` branch is not in `$BRANCHES` but is handled explicitly in several scripts (PUSH, DIFF, RESET, TAG). -- 2.39.5