Skip to content

docs(claude): document Flyway migrations in CLAUDE.md #340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nanotaboada merged 2 commits into from
Jun 8, 2026
Merged

docs(claude): document Flyway migrations in CLAUDE.md #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a0d097
docs(claude): document Flyway migrations in CLAUDE.md
nanotaboada Jun 8, 2026
67fb3ff
fix(changelog): merge duplicate ### Changed headings in Unreleased
nanotaboada Jun 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ Release names follow the **historic football clubs** naming convention (A–Z):

### Changed

- Update `CLAUDE.md`: add Flyway to Tech Stack, add `db/migration/` to structure
diagram, fix "Modify schema" workflow to use versioned Flyway migrations instead
of manually editing the SQLite file — produced with the
[CLAUDE.md Management plugin](https://claude.com/plugins/claude-md-management)
- Consolidate project documentation into `CLAUDE.md` as the single source of
truth; add Invariants and Architecture Decision Records sections; extend
Pre-commit Checks with ADR update requirement (#335)
Expand Down
8 changes: 5 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ REST API for managing football players built with Java and Spring Boot. Implemen
- **Validation**: Bean Validation (JSR-380)
- **Caching**: Spring `@Cacheable` (simple in-memory, no expiry)
- **Mapping**: ModelMapper
- **Migrations**: Flyway (versioned SQL under `db/migration/`; disabled in tests — tests use Spring SQL init instead)
- **Logging**: SLF4J
- **Testing**: JUnit 5 + AssertJ + MockMvc + Mockito
- **Coverage**: JaCoCo
Expand All @@ -31,9 +32,10 @@ src/main/java/
├── models/ — Player entity + DTOs
└── converters/ — JPA AttributeConverter for ISO-8601 date handling
src/main/resources/ — application.properties, Logback config
src/main/resources/db/migration/ — Flyway versioned SQL (V1 schema, V2+V3 seed data; add V{N}__ here to change schema)
src/test/java/ — test classes mirroring main structure
src/test/resources/ — test config, schema (ddl.sql), seed data (dml.sql)
storage/ — SQLite database file (runtime)
src/test/resources/ — test config, schema (ddl.sql), seed data (dml.sql); Flyway disabled in tests
storage/ — SQLite database file (runtime, created and populated by Flyway on first start)
```

**Layer rule**: `Controller → Service → Repository → JPA`. Controllers must not access repositories directly. Business logic must not live in controllers.
Expand Down Expand Up @@ -133,7 +135,7 @@ This project uses Spec-Driven Development (SDD): discuss in Plan mode first, cre

**Add an endpoint**: Define DTO in `models/` with Bean Validation → add service method in `services/` with `@Transactional` → create controller endpoint with `@Operation` annotation → add tests → run `./mvnw clean test jacoco:report`.

**Modify schema**: Update `@Entity` in `models/Player.java` → update DTOs if API changes → manually update `storage/players-sqlite3.db` (preserve 26 players) → update service, repository, and tests → run `./mvnw clean test`.
**Modify schema**: Create a new Flyway migration `src/main/resources/db/migration/V{N}__description.sql` (production path) → update `@Entity` in `models/Player.java` → update DTOs if API changes → also update `src/test/resources/ddl.sql` and `dml.sql` (tests use Spring SQL init, not Flyway) → update service, repository, and tests → run `./mvnw clean test`. Do not manually edit the SQLite file in `storage/`; Flyway owns it.

**After completing work**: Suggest a branch name (e.g. `feat/add-player-stats`) and a commit message following Conventional Commits including co-author line:

Expand Down