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>
3.7 KiB
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. TheirTABLE_NAMEand 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 inCmsTables.VALUE_LISTSand named on the field by its logical name.metadata:CmsTableBuilder(tables, possible values, joins, child lists, associations, permission rules),CmsAppBuilderandCmsAreas(apps and homes).home:CmsHomeRendererandCmsHtml(one renderer for every home; reads run withPermissionEnforcement.ENFORCE).security:CmsRole,CmsSecurity,CmsOpenReadsPermissionChecker.- Schema:
src/main/resources/qbit-cms/db/changelog/qbit-cms.changelog.yaml. Its changesets are append-only once released:CmsChangelogReleasedTestfails the build when a released changeset differs fromsrc/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.sqlis 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>andcms.<action>(for examplecms.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-activeqqq-snapshotprofile importsqqq-bom-pom:4.1.0-RC.4ahead 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.
developpublishes SNAPSHOTs.- A
release/*branch publishes RCs (the orb bumps the version). - A
v*tag publishes the release.