Files
James MaesandClaude Fable 5.2 d7774fd734
maven / build (push) Successful in 1m37s
build / maven (push) Successful in 1m37s
fix: hold the changelog to its released changesets, and waive no checksum
0.1.0-RC.3 took runAlways off the released changeset
1.0.0-guard-existing-tables and gave it validCheckSum: ANY. The rule of this
changelog is that a released changeset never changes.

- the waiver is removed: it was not needed (the changeset's changes are what
  they were, so the checksum existing installs recorded is still valid) and
  it switched off checksum protection for that changeset for good
- CmsChangelogReleasedTest migrates an install made by the 0.1.0-RC.2
  changelog as tagged with the current one and asserts that its history
  rows are untouched
- the same test fails the build when a released changeset differs from the
  recorded release, runs on every migration, or waives its checksum
- the one exception (runAlways removed from the guard) is recorded where
  the rule is written

Tests: 42 run, 0 failures, Checkstyle 0.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-19 05:10:22 -06:00

57 lines
3.7 KiB
Markdown

# CLAUDE.md
This file provides guidance to Claude Code when working with code in this repository.
## Project Overview
**QBit CMS**: QQQ QBit: a headless CMS (sites, pages, menus, blog, media, projects, photos and publishing) as standard QQQ tables, extracted from the kof22 website. Design: [QRun-IO/qqq#1083](https://github.com/QRun-IO/qqq/pull/1083) (decisions D1 to D17, all accepted). Implementation in progress.
## Build Commands
```bash
./mvnw compile # Compile (always use the wrapper: Maven 3.10 cannot read the parent POM)
./mvnw test # Unit tests
./mvnw verify # Unit tests + JaCoCo gate (70% instructions, 90% classes)
```
## Architecture
**Entry point:** `CmsQBitProducer implements QBitMetaDataProducer<CmsQBitConfig>` in `com.kingsrook.qbits.cms`. The producer builds every table, possible-value source, app and widget itself (no package scanning); `CmsFeature` flags switch feature areas on and off. The schema is a prefix-parameterized Liquibase changelog the host includes and runs (`src/main/resources/qbit-cms/db/changelog/`); the qbit never runs DDL.
Packages:
- `CmsQBitConfig`, `CmsFeature`, `CmsTables` (logical names and table definitions), `CmsRuntime`, `CmsSchemaCheck` (startup check), `CmsStartupMode`.
- `core/model`: CORE entities. Their `TABLE_NAME` and possible-value source names are logical; the builder adds the prefix.
- `media/model`, `blog/model`, `projects/model`, `photos/model`: the content features' entities and their value-list enums (same rule). A value list is registered in `CmsTables.VALUE_LISTS` and named on the field by its logical name.
- `metadata`: `CmsTableBuilder` (tables, possible values, joins, child lists, associations, permission rules), `CmsAppBuilder` and `CmsAreas` (apps and homes).
- `home`: `CmsHomeRenderer` and `CmsHtml` (one renderer for every home; reads run with `PermissionEnforcement.ENFORCE`).
- `security`: `CmsRole`, `CmsSecurity`, `CmsOpenReadsPermissionChecker`.
- Schema: `src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml`. Its changesets are append-only once released: `CmsChangelogReleasedTest` fails the build when a released changeset differs from `src/test/resources/released/qbit-cms.changelog.released.yaml`, when one runs on every migration or waives its checksum, and when an install of the first release does not migrate on. When a release is cut, copy the changelog over that file in the same change. `docs/ddl/postgres.sql` is generated from the changelog.
## Naming (owner rule)
- Tables are lowercase snake_case prefixed with the full qbit name: `cms_<name>`. The QQQ table name and the backend (SQL) name are identical; possible-value sources take the table name.
- Permissions use the full qbit name: `cms.<table>.<action>` and `cms.<action>` (for example `cms.cms_page.edit`, `cms.publish`).
- Qbit data lives in standard, visible QQQ tables, secured by permissions and record security locks, never hidden.
- Processes run as table or record actions, never in the nav.
## Code Style
- 3-space indentation, opening braces on the next line, `return (x);`.
- Javadoc flower-box comments (`/*****` with `**` lines) on every class and method.
- Fluent setters (`withX()`).
- Wrapper types (`Integer`, `Boolean`) in config and entities.
## Dependencies
- Java 21.
- Parent `com.kingsrook:qbit-build-parent:2.0.0` (qqq 4.0.0). The default-active `qqq-snapshot` profile imports `qqq-bom-pom:4.1.0-RC.4` ahead of it, as in qbit-quick-search (ADR-0007). Remove that activation when the parent moves to 4.1.
- Tests: JUnit 5, AssertJ.
## Release
- CircleCI qqq-orb 0.6.8.
- `develop` publishes SNAPSHOTs.
- A `release/*` branch publishes RCs (the orb bumps the version).
- A `v*` tag publishes the release.