Compare commits

...
Author SHA1 Message Date
James MaesandClaude Fable 5.2 7270619359 Merge develop into release/0.1 (fix: hold the changelog to its released changesets, and waive no checksum)
maven / build (push) Successful in 2m29s
build / maven (push) Successful in 2m29s
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-19 05:12:37 -06:00
james.maes 99f385a869 Merge pull request 'fix: hold the changelog to its released changesets, and waive no checksum' (#32) from fix/changelog-append-only into develop
maven / build (push) Successful in 2m5s
build / maven (push) Successful in 2m5s
2026-11-19 11:12:31 +00:00
James MaesandClaude Fable 5.2 d7774fd734 fix: hold the changelog to its released changesets, and waive no checksum
maven / build (push) Successful in 1m37s
build / maven (push) Successful in 1m37s
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
CI 6a1fd1e13a Bump version to 0.1.0-RC.3 [skip ci] 2026-11-18 22:52:44 +00:00
james.maes fea5e19a7f Merge pull request 'Merge develop into release/0.1 (next release candidate)' (#31) from merge/develop-into-release-0.1 into release/0.1
maven / build (push) Successful in 2m18s
build / maven (push) Successful in 2m17s
2026-11-18 22:50:27 +00:00
James MaesandClaude Fable 5.2 752f0d9997 Merge develop into release/0.1 (media, blog, projects, photos; help; includable changelog)
maven / build (push) Successful in 1m45s
build / maven (push) Successful in 1m45s
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-18 16:47:15 -06:00
james.maes d2cdb64fb1 Merge pull request 'feat: media, blog, projects and photos features, the qbit's own help, and a changelog a host can include' (#30) from feature/content-features into develop
maven / build (push) Successful in 2m2s
build / maven (push) Successful in 2m2s
2026-11-18 22:22:21 +00:00
CI 37f5925dba Bump version to 0.1.0-RC.2 [skip ci] 2026-11-07 18:17:09 +00:00
james.maes e4c4c42aa6 Merge pull request 'Merge develop into release/0.1 (Gitea-aligned RC)' (#29) from align/develop-into-release-0.1 into release/0.1
maven / build (push) Successful in 4m4s
build / maven (push) Successful in 4m4s
2026-11-07 18:11:15 +00:00
james.maesandClaude Opus 5.5 08b91db75a Merge develop into release/0.1 (Gitea-aligned RC)
maven / build (push) Canceled after 0s
build / maven (push) Canceled after 0s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 12:10:57 -06:00
Gitea Actions 39ed316522 Bump version to 0.1.0-RC.1 [skip ci] 2026-11-05 14:44:03 +00:00
10 changed files with 4180 additions and 19 deletions

No files matched your search

+1 -1
View File
@@ -26,7 +26,7 @@ Packages:
- `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, and `docs/ddl/postgres.sql` is generated from it.
- 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)
+2 -1
View File
@@ -25,4 +25,5 @@ All notable changes to this project are documented here. The format follows Keep
### Schema changes
- `1.0.0` baseline: a prefix-parameterized Liquibase changelog (`qbit-cms/db/changelog/qbit-cms.changelog.yaml`, logical path `qbit-cms/changelog`). It creates the CORE tables with the kof22 column types, adds their foreign keys and indexes, and seeds generic reference data. Feature sections are gated by `cms.features`, and a name collision halts the install. Reference DDL is in `docs/ddl/postgres.sql`.
- `1.0.0` content tables, appended to the same changelog: `1.0.0-create-<table>` for the eighteen tables of `MEDIA`, `BLOG`, `PROJECTS` and `PHOTOS`, `1.0.0-constraints-<feature>` for each feature's foreign keys and indexes, `1.0.0-constraints-blog-projects` and `1.0.0-constraints-photos-projects` for the links between two features, and `1.0.0-seed-media_type` and `1.0.0-seed-blog_type` for generic reference data. Each is gated by `cms.features` and by the features it needs. `1.0.0-guard-existing-content-tables` halts the install when a table with one of these names already exists; it runs once, not on every run.
- **Changed, on purpose, in a released changeset:** `1.0.0-guard-existing-tables` no longer has `runAlways`. It rewrote its `DATABASECHANGELOG` row on every migration, so a second migration was never a no-op and a rollback by count began with it; a host whose migrations must be repeatable could not include this changelog and had to copy the tables instead. It now runs once, before the tables are created, and carries `validCheckSum: ANY` so an install that already ran it migrates on unchanged (`CmsInstallTest.testRerunIsNoop` covers both). A table that appears later under a qbit name still stops the install, at its `createTable`. Check constraints as in kof22: the value-list columns of `media_type`, `blog_post_version` and `project` (the project status check is new), `media_type.max_file_size_mb` above zero and the focal point of a project's image between 0 and 100. `project_category.section` is optional (kof22 requires it); latitude and longitude columns are `DOUBLE PRECISION` as in kof22. A host that already runs `CORE` gets the content tables at its next migration run unless its `cms.features` leaves them out.
- **Changed, on purpose, in a released changeset (the one recorded exception to "released changesets never change"):** `1.0.0-guard-existing-tables` no longer has `runAlways`. It rewrote its `DATABASECHANGELOG` row on every migration, so a second migration was never a no-op and a rollback by count began with it; a host whose migrations must be repeatable could not include the changelog. Only that attribute changed: the changeset's changes are what they were, so the checksum an existing install recorded is still its checksum and nothing is waived (`0.1.0-RC.3` carried `validCheckSum: ANY`, which was not needed and is removed). `CmsChangelogReleasedTest` migrates an install made by the `0.1.0-RC.2` changelog as tagged and asserts that its history rows are untouched, and from now on fails the build when any released changeset differs from `src/test/resources/released/qbit-cms.changelog.released.yaml`, runs on every migration or waives its checksum. What the guard no longer does: check for a name collision again at a later migration. A feature switched on later still cannot adopt a foreign table, because creating a table that exists fails; the message is the database's and not the guard's.
- Check constraints as in kof22: the value-list columns of `media_type`, `blog_post_version` and `project` (the project status check is new), `media_type.max_file_size_mb` above zero and the focal point of a project's image between 0 and 100. `project_category.section` is optional (kof22 requires it); latitude and longitude columns are `DOUBLE PRECISION` as in kof22. A host that already runs `CORE` gets the content tables at its next migration run unless its `cms.features` leaves them out.
+1 -1
View File
@@ -26,7 +26,7 @@ Packages:
- `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, and `docs/ddl/postgres.sql` is generated from it.
- 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)
+1 -1
View File
@@ -19,7 +19,7 @@
<properties>
<qqq.version>4.1.0-RC.26</qqq.version> <!-- feeds qbit-build-parent's qqq-bom-pom import -->
<revision>0.1.0-SNAPSHOT</revision>
<revision>0.1.0-RC.3</revision>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
<jacoco.version>0.8.15</jacoco.version>
@@ -6,7 +6,9 @@
# cms.tablePrefix table name prefix, must equal CmsQBitConfig.tableNamePrefix (default cms_)
# cms.features comma-separated CmsFeature names to install (default: all)
# cms.seedReferenceData insert the generic redirect, page and section types (default true)
# Changesets are only ever appended; released changesets never change.
# Changesets are only ever appended; released changesets never change (CmsChangelogReleasedTest holds the build to
# it). One exception is recorded: 0.1.0-RC.3 took runAlways off 1.0.0-guard-existing-tables; its changes, and so
# its checksum, are what they were.
databaseChangeLog:
- property: { name: cms.tablePrefix, value: cms_ }
- property: { name: cms.features, value: "CORE,MEDIA,BLOG,PROJECTS,PHOTOS,PUBLISHING,STREAM" }
@@ -16,12 +18,12 @@ databaseChangeLog:
# changelog (a name collision): choose another cms.tablePrefix.
# It runs once, before the tables are created. Up to 0.1.0-RC.2 it ran on every migration (runAlways), which made
# every run rewrite its row in DATABASECHANGELOG: a second migration was never a no-op and a rollback by count
# began with this changeset. An install that already ran it keeps its row; validCheckSum accepts what it recorded.
# began with this changeset. An install that already ran it keeps its row: the changes below are unchanged, so the
# checksum it recorded is still this changeset's, and nothing is waived.
- changeSet:
id: 1.0.0-guard-existing-tables
author: qbit-cms
logicalFilePath: qbit-cms/changelog
validCheckSum: ANY
preConditions:
- onFail: HALT
- onFailMessage: "A table named ${cms.tablePrefix}<name> exists but was not created by qbit-cms; set a different cms.tablePrefix"
@@ -0,0 +1,157 @@
/*
* Copyright © 2026. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com | https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.cms;
import java.io.InputStream;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager;
import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
import org.junit.jupiter.api.Test;
import org.yaml.snakeyaml.Yaml;
import static org.assertj.core.api.Assertions.assertThat;
/*******************************************************************************
** The changelog's contract with installs that already ran it: a released
** changeset never changes, and new versions only append.
**
** Two files under src/test/resources/released hold what has shipped:
** - qbit-cms.changelog-0.1.0-RC.2.yaml, the first release, as tagged. An
** install made by it must migrate on with the current changelog, with no
** checksum waiver, and its history must stay as it was.
** - qbit-cms.changelog.released.yaml, the changelog as of the latest release.
** Every changeset in it must be in the current changelog unchanged and in
** the same order; new changesets go after them. When a release is cut, copy
** the current changelog over that file in the same change.
**
** One exception is recorded: 0.1.0-RC.3 took runAlways off the first guard
** changeset (it rewrote its history row on every migration). Its changes are
** what they were, so its checksum is the one existing installs recorded.
*******************************************************************************/
class CmsChangelogReleasedTest
{
private static final String FIRST_RELEASE = "released/qbit-cms.changelog-0.1.0-RC.2.yaml";
private static final String RELEASED = "released/qbit-cms.changelog.released.yaml";
private static final String GUARD = "1.0.0-guard-existing-tables";
/*******************************************************************************
** An install of the first release, migrated more than once as its guard did,
** migrates on with the current changelog: no checksum is waived, the rows it
** recorded are untouched, the content tables arrive, and a further migration
** changes nothing.
*******************************************************************************/
@Test
void testAnInstallOfTheFirstReleaseMigratesOn() throws Exception
{
RDBMSBackendMetaData backend = CmsTestSupport.h2Backend();
CmsTestSupport.migrate(backend, FIRST_RELEASE, Map.of());
CmsTestSupport.migrate(backend, FIRST_RELEASE, Map.of());
Map<String, String> first = history(backend);
assertThat(first).containsKey(GUARD);
assertThat(first.get(GUARD)).as("the first release ran its guard on every migration").contains("|RERAN");
CmsTestSupport.migrate(backend, Map.of());
Map<String, String> upgraded = history(backend);
for(Map.Entry<String, String> row : first.entrySet())
{
assertThat(upgraded.get(row.getKey())).as("the history row of " + row.getKey() + " after the upgrade").isEqualTo(row.getValue());
}
assertThat(upgraded.keySet()).as("the content tables are created by the upgrade").contains("1.0.0-create-media", "1.0.0-create-blog_post");
CmsTestSupport.migrate(backend, Map.of());
assertThat(history(backend)).as("the history after a further migration").isEqualTo(upgraded);
}
/*******************************************************************************
** Every released changeset is in the current changelog, unchanged and in the
** same order; whatever is new comes after them. None runs on every migration.
*******************************************************************************/
@Test
void testReleasedChangesetsNeverChange() throws Exception
{
List<Map<String, Object>> released = changeSets(RELEASED);
List<Map<String, Object>> current = changeSets(CmsQBitConfig.CHANGELOG);
assertThat(released).hasSizeGreaterThan(40);
assertThat(current.size()).as("changesets are only ever appended").isGreaterThanOrEqualTo(released.size());
for(int i = 0; i < released.size(); i++)
{
assertThat(current.get(i)).as("released changeset " + released.get(i).get("id") + " (position " + i + ")").isEqualTo(released.get(i));
}
for(Map<String, Object> changeSet : current)
{
assertThat(changeSet).as("changeset " + changeSet.get("id") + " must not run on every migration").doesNotContainKey("runAlways");
assertThat(changeSet).as("changeset " + changeSet.get("id") + " must not waive its checksum").doesNotContainKey("validCheckSum");
}
}
/*******************************************************************************
** The change sets of a changelog on the classpath, in file order.
*******************************************************************************/
@SuppressWarnings("unchecked")
private static List<Map<String, Object>> changeSets(String path) throws Exception
{
try(InputStream in = CmsChangelogReleasedTest.class.getClassLoader().getResourceAsStream(path))
{
assertThat(in).as(path).isNotNull();
Map<String, Object> root = new Yaml().load(in);
List<Map<String, Object>> entries = (List<Map<String, Object>>) root.get("databaseChangeLog");
List<Map<String, Object>> changeSets = new ArrayList<>();
for(Map<String, Object> entry : entries)
{
if(entry.containsKey("changeSet"))
{
changeSets.add((Map<String, Object>) entry.get("changeSet"));
}
}
return (changeSets);
}
}
/*******************************************************************************
** The migration history by changeset id: order, date, checksum and how it ran.
*******************************************************************************/
private static Map<String, String> history(RDBMSBackendMetaData backend) throws Exception
{
Map<String, String> rows = new LinkedHashMap<>();
try(Connection connection = ConnectionManager.getConnection(backend); Statement statement = connection.createStatement();
ResultSet resultSet = statement.executeQuery("SELECT ID, ORDEREXECUTED, DATEEXECUTED, MD5SUM, EXECTYPE FROM DATABASECHANGELOG ORDER BY ORDEREXECUTED, ID"))
{
while(resultSet.next())
{
rows.put(resultSet.getString(1), resultSet.getString(2) + "|" + resultSet.getString(3) + "|" + resultSet.getString(4) + "|" + resultSet.getString(5));
}
}
return (rows);
}
}
@@ -139,9 +139,8 @@ class CmsInstallTest
/*******************************************************************************
** Running the changelog again changes nothing, the migration history
** included: a host whose migrations must be repeatable can include it. An
** install recorded by the earlier version, whose guard ran on every
** migration, migrates on without complaint.
** included: a host whose migrations must be repeatable can include it.
** (An install of the first release migrating on: CmsChangelogReleasedTest.)
*******************************************************************************/
@Test
void testRerunIsNoop() throws Exception
@@ -153,14 +152,6 @@ class CmsInstallTest
assertThat(history(backend)).as("the migration history after a second run").isEqualTo(history);
assertThat(history).hasSizeGreaterThan(40).anyMatch(row -> row.startsWith("1.0.0-guard-existing-tables|"));
try(Connection connection = ConnectionManager.getConnection(backend); Statement statement = connection.createStatement())
{
statement.execute("UPDATE DATABASECHANGELOG SET MD5SUM = '9:00000000000000000000000000000000', EXECTYPE = 'RERAN' WHERE ID = '1.0.0-guard-existing-tables'");
}
List<String> earlier = history(backend);
CmsTestSupport.migrate(backend, Map.of());
assertThat(history(backend)).as("the history of an install the earlier version recorded").isEqualTo(earlier);
QInstance qInstance = CmsTestSupport.blankInstance(backend);
CmsQBitConfig config = new CmsQBitConfig().withBackendName(CmsTestSupport.BACKEND);
new CmsQBitProducer().withQBitConfig(config).produce(qInstance);
@@ -92,10 +92,20 @@ public final class CmsTestSupport
** with the given changelog properties.
*******************************************************************************/
public static void migrate(RDBMSBackendMetaData backend, Map<String, String> properties) throws Exception
{
migrate(backend, CmsQBitConfig.CHANGELOG, properties);
}
/*******************************************************************************
** Run a changelog of the classpath (a released one, for upgrade tests).
*******************************************************************************/
public static void migrate(RDBMSBackendMetaData backend, String changelog, Map<String, String> properties) throws Exception
{
Connection connection = ConnectionManager.getConnection(backend);
Database database = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(new JdbcConnection(connection));
try(Liquibase liquibase = new Liquibase(CmsQBitConfig.CHANGELOG, new ClassLoaderResourceAccessor(), database))
try(Liquibase liquibase = new Liquibase(changelog, new ClassLoaderResourceAccessor(), database))
{
properties.forEach(liquibase::setChangeLogParameter);
liquibase.update(new Contexts(), new LabelExpression());
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff