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

3.7 KiB

AGENTS.md

This file provides guidance to Codex 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 (decisions D1 to D17, all accepted). Implementation in progress.

Build Commands

./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.