build: re-pin to qbit-build-parent 2.0.0, add qqq-snapshot profile (QRun-IO/qqq#769) #3

2026-09-26T01:45:06Z

KofTwentyTwo commented

2026-09-26 01:45:06 +00:00

(Migrated from github.com)

Summary

Re-pins qbit-geo-data to com.kingsrook:qbit-build-parent:2.0.0 (qqq 4.0.0 GA). Adds an opt-in qqq-snapshot profile that builds and tests against qqq 4.1.0-SNAPSHOT, so qqq-all can include this qbit. The first commit back-merges main into develop.

This PR must be merged with a merge commit (not squash or rebase). A merge commit keeps the three main commits in develop's history. Without it, main and develop stay diverged.

Closes QRun-IO/qqq#769
Part of QRun-IO/qqq-all#1

Changes

chore: merge main into develop: git merge --no-ff origin/main (details below).
build: re-pin to qbit-build-parent 2.0.0 (qqq 4.0.0): parent 1.5.1 -> 2.0.0. The parent imports qqq-bom-pom 4.0.0, and qqq-backend-core / qqq-backend-module-rdbms now resolve to 4.0.0 (they were on 0.35.0). Still Java 21.
build: add opt-in qqq-snapshot profile: root-pom profile that imports qqq-bom-pom:${qqq.snapshot.version} (default 4.1.0-SNAPSHOT) ahead of the parent's BOM and adds the Central snapshots repository (https://central.sonatype.com/repository/maven-snapshots/). Both modules inherit it. Default builds don't change.
ci: keep apt unattended on CircleCI machine images: adds the configure-package-install command from qbit-quick-search develop and uses it as a pre-steps entry on all five orb jobs. This stops needrestart from stalling install_java (QRun-IO/qqq-orb#11). The orb version (0.5.0) is unchanged.
docs: note qqq 4.0.0 re-pin and Java 21 prerequisite: CHANGELOG entry. The getting-started prerequisites now say Java 21+ / QQQ 4.0.0+ (they said Java 17+ / QQQ 0.23.0+).

Plan steps with nothing to change:

Step 2, shadowing qqq-bom-pom imports: the child poms had none.
Step 4, Docker integration tests: this repo has none (no Testcontainers or Docker usage, and no skipped or assumed tests).
Step 5, explicit qqq module versions: none. The qqq dependencies already had no <version>, so the BOM or the profile controls them.

Back-merge (`main` -> `develop`) resolutions

main had 3 commits not in develop. The merge had no conflicts: every file main added is new to develop, and nothing develop changed overlaps with them.

d9f902e chore: migrate license from AGPL-3.0 to Apache-2.0: adds LICENSE (Apache-2.0) and NOTICE. Taken from main as is. develop had no LICENSE file.
f7889fd chore: add CODEOWNERS pointing to sole maintainer: adds .github/CODEOWNERS. Taken from main.
ebb950f: adds the root-level knowledge-base pointer doc (a link to the QQQ knowledge-base dossier). Taken from main.
Kept from develop: its .gitignore addition, the removal of a local editor settings file (e6a2ce7), and the 0.2.0-SNAPSHOT revision.

Licensing: this PR doesn't edit LICENSE files, NOTICE, or source headers. LICENSE/NOTICE arrive from main unchanged. The pom <licenses> block still says AGPL-3.0 and is left alone, because license alignment is a separate owner decision.

Related Issues

Closes QRun-IO/qqq#769
Part of QRun-IO/qqq-all#1
Related: QRun-IO/qqq-orb#11 (needrestart workaround)

Type of Change

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Refactoring (no functional changes)
Dependencies update

Testing

Commands run from the repo root (no mvnw in this repo). All on Maven 3.9.16 and Java 21.0.12.

Command	Result
`mvn -B verify` (baseline, before the re-pin, qqq 0.35.0)	BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped
`mvn -B -Pqqq-snapshot dependency:list -pl qbit-geo-data-core` (before adding the profile)	warning "profile qqq-snapshot does not exist"; qqq resolved to 4.0.0 (expected red)
`mvn -B dependency:list -pl qbit-geo-data-core -DincludeGroupIds=com.kingsrook.qqq`	`qqq-backend-core:4.0.0`, `qqq-backend-module-rdbms:4.0.0`
`mvn -B -U -Pqqq-snapshot dependency:list -pl qbit-geo-data-core -DincludeGroupIds=com.kingsrook.qqq`	`qqq-backend-core:4.1.0-SNAPSHOT`, `qqq-backend-module-rdbms:4.1.0-SNAPSHOT` (downloaded from Central snapshots)
`mvn -B clean` then `mvn -B verify` (final gate)	BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped
`mvn -B clean` then `mvn -B -U -Pqqq-snapshot verify` (final gate)	BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped

Liquibase changelog generator: its 6 unit tests (GeoDataLiquibaseGeneratorTest) pass in both gates. As an extra end-to-end check, I ran GeoDataLiquibaseGenerator.generate(config, path) through jshell on the -Pqqq-snapshot classpath (qqq-backend-core-4.1.0-SNAPSHOT.jar), with prefix shipping and cities disabled. It wrote a changelog that passes xmllint --noout, with 2 createTable changesets (shipping_country, shipping_state_province) and no city section.

CircleCI config: circleci config validate can't resolve kingsrook/qqq-orb from this machine. It fails the same way ("Cannot find kingsrook/qqq-orb@... in the orb registry") on the unmodified develop config and on qbit-quick-search's develop config, which does run on CI. Instead I compared the parsed YAML with yq. The commands block is identical to qbit-quick-search develop, and all 5 jobs carry pre-steps: [configure-package-install].

Unit tests pass (mvn test)
Integration tests pass (mvn verify)
Manual testing performed (generator run end to end on 4.1.0-SNAPSHOT)

Checklist

My code follows the project's style guidelines
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works (build-only change; the profile was checked with the dependency resolution runs above)
New and existing unit tests pass locally with my changes

Screenshots (if applicable)

Not applicable.

Additional Notes

Merge with a merge commit. Squash or rebase would drop the back-merge of main.
The Maven warning Failed to build parent project for com.kingsrook.qbits:qbit-geo-data-parent was already there before this PR. It appears the same way on the baseline build with parent 1.5.1.
Left alone to keep scope tight: the child junit-bom 5.10.0 import still takes precedence over the parent's junit-bom 6.0.1, and the orb stays on kingsrook/qqq-orb@0.5.0.
The move to a 4.1 parent happens at qqq 4.1 GA (plan task C9, QRun-IO/qqq-all#10).

## Summary Re-pins qbit-geo-data to `com.kingsrook:qbit-build-parent:2.0.0` (qqq 4.0.0 GA). Adds an opt-in `qqq-snapshot` profile that builds and tests against qqq 4.1.0-SNAPSHOT, so qqq-all can include this qbit. The first commit back-merges `main` into `develop`. **This PR must be merged with a merge commit (not squash or rebase).** A merge commit keeps the three `main` commits in `develop`'s history. Without it, `main` and `develop` stay diverged. Closes QRun-IO/qqq#769 Part of QRun-IO/qqq-all#1 ## Changes - `chore: merge main into develop`: `git merge --no-ff origin/main` (details below). - `build: re-pin to qbit-build-parent 2.0.0 (qqq 4.0.0)`: parent 1.5.1 -> 2.0.0. The parent imports `qqq-bom-pom` 4.0.0, and `qqq-backend-core` / `qqq-backend-module-rdbms` now resolve to 4.0.0 (they were on 0.35.0). Still Java 21. - `build: add opt-in qqq-snapshot profile`: root-pom profile that imports `qqq-bom-pom:${qqq.snapshot.version}` (default `4.1.0-SNAPSHOT`) ahead of the parent's BOM and adds the Central snapshots repository (`https://central.sonatype.com/repository/maven-snapshots/`). Both modules inherit it. Default builds don't change. - `ci: keep apt unattended on CircleCI machine images`: adds the `configure-package-install` command from qbit-quick-search `develop` and uses it as a `pre-steps` entry on all five orb jobs. This stops needrestart from stalling `install_java` (QRun-IO/qqq-orb#11). The orb version (0.5.0) is unchanged. - `docs: note qqq 4.0.0 re-pin and Java 21 prerequisite`: CHANGELOG entry. The getting-started prerequisites now say Java 21+ / QQQ 4.0.0+ (they said Java 17+ / QQQ 0.23.0+). Plan steps with nothing to change: - Step 2, shadowing `qqq-bom-pom` imports: the child poms had none. - Step 4, Docker integration tests: this repo has none (no Testcontainers or Docker usage, and no skipped or assumed tests). - Step 5, explicit qqq module versions: none. The qqq dependencies already had no `<version>`, so the BOM or the profile controls them. ### Back-merge (`main` -> `develop`) resolutions `main` had 3 commits not in `develop`. The merge had **no conflicts**: every file `main` added is new to `develop`, and nothing `develop` changed overlaps with them. - `d9f902e chore: migrate license from AGPL-3.0 to Apache-2.0`: adds `LICENSE` (Apache-2.0) and `NOTICE`. Taken from `main` as is. `develop` had no LICENSE file. - `f7889fd chore: add CODEOWNERS pointing to sole maintainer`: adds `.github/CODEOWNERS`. Taken from `main`. - `ebb950f`: adds the root-level knowledge-base pointer doc (a link to the QQQ knowledge-base dossier). Taken from `main`. - Kept from `develop`: its `.gitignore` addition, the removal of a local editor settings file (`e6a2ce7`), and the `0.2.0-SNAPSHOT` revision. Licensing: this PR doesn't edit LICENSE files, NOTICE, or source headers. `LICENSE`/`NOTICE` arrive from `main` unchanged. The pom `<licenses>` block still says AGPL-3.0 and is left alone, because license alignment is a separate owner decision. ## Related Issues Closes QRun-IO/qqq#769 Part of QRun-IO/qqq-all#1 Related: QRun-IO/qqq-orb#11 (needrestart workaround) ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [x] Documentation update - [ ] Refactoring (no functional changes) - [x] Dependencies update ## Testing Commands run from the repo root (no `mvnw` in this repo). All on Maven 3.9.16 and Java 21.0.12. | Command | Result | |---|---| | `mvn -B verify` (baseline, before the re-pin, qqq 0.35.0) | BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped | | `mvn -B -Pqqq-snapshot dependency:list -pl qbit-geo-data-core` (before adding the profile) | warning "profile qqq-snapshot does not exist"; qqq resolved to 4.0.0 (expected red) | | `mvn -B dependency:list -pl qbit-geo-data-core -DincludeGroupIds=com.kingsrook.qqq` | `qqq-backend-core:4.0.0`, `qqq-backend-module-rdbms:4.0.0` | | `mvn -B -U -Pqqq-snapshot dependency:list -pl qbit-geo-data-core -DincludeGroupIds=com.kingsrook.qqq` | `qqq-backend-core:4.1.0-SNAPSHOT`, `qqq-backend-module-rdbms:4.1.0-SNAPSHOT` (downloaded from Central snapshots) | | `mvn -B clean` then `mvn -B verify` (final gate) | BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped | | `mvn -B clean` then `mvn -B -U -Pqqq-snapshot verify` (final gate) | BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped | Liquibase changelog generator: its 6 unit tests (`GeoDataLiquibaseGeneratorTest`) pass in both gates. As an extra end-to-end check, I ran `GeoDataLiquibaseGenerator.generate(config, path)` through `jshell` on the `-Pqqq-snapshot` classpath (`qqq-backend-core-4.1.0-SNAPSHOT.jar`), with prefix `shipping` and cities disabled. It wrote a changelog that passes `xmllint --noout`, with 2 `createTable` changesets (`shipping_country`, `shipping_state_province`) and no city section. CircleCI config: `circleci config validate` can't resolve `kingsrook/qqq-orb` from this machine. It fails the same way ("Cannot find kingsrook/qqq-orb@... in the orb registry") on the unmodified `develop` config and on qbit-quick-search's `develop` config, which does run on CI. Instead I compared the parsed YAML with `yq`. The `commands` block is identical to qbit-quick-search `develop`, and all 5 jobs carry `pre-steps: [configure-package-install]`. - [x] Unit tests pass (`mvn test`) - [x] Integration tests pass (`mvn verify`) - [x] Manual testing performed (generator run end to end on 4.1.0-SNAPSHOT) ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works (build-only change; the profile was checked with the dependency resolution runs above) - [x] New and existing unit tests pass locally with my changes ## Screenshots (if applicable) Not applicable. ## Additional Notes - Merge with a **merge commit**. Squash or rebase would drop the back-merge of `main`. - The Maven warning `Failed to build parent project for com.kingsrook.qbits:qbit-geo-data-parent` was already there before this PR. It appears the same way on the baseline build with parent 1.5.1. - Left alone to keep scope tight: the child `junit-bom` 5.10.0 import still takes precedence over the parent's `junit-bom` 6.0.1, and the orb stays on `kingsrook/qqq-orb@0.5.0`. - The move to a 4.1 parent happens at qqq 4.1 GA (plan task C9, QRun-IO/qqq-all#10).

KofTwentyTwo commented

2026-09-26 01:53:03 +00:00

(Migrated from github.com)

Review, round 1 (plan task B7, QRun-IO/qqq#769)

PR #3: build: re-pin to qbit-build-parent 2.0.0, add qqq-snapshot profile
Tier: Deep (2 risk signals)
Sized: 289/3 across 8 files (202 of the additions are LICENSE)
Risk signals: build/release (.circleci/config.yml), dependency/build change (pom.xml parent and repository)
Routing to: pr-review-toolkit:review-pr (code-reviewer and comment-analyzer passes; no test, error-handling or type changes), plus a manual security pass

Verdict: approve. No blocking issues.

B7 requirements

Step	Status	Evidence
1. Back-merge `main` into `develop`	Met, but inside this PR (see note 1)	`819b3da` is a two-parent merge (`b9eaa6c` + `ebb950f`). Compared with `develop`, it adds only CODEOWNERS, CLAUDE.md, LICENSE and NOTICE. Compared with `main`, it keeps only develop's `.gitignore`, the `.claude/settings.local.json` removal and the `0.2.0-SNAPSHOT` revision. Nothing was lost.
2. Parent 2.0.0, Java 21, no shadowing qqq BOM, licenses untouched	Met	Parent is `qbit-build-parent:2.0.0`. The child poms have no `qqq-bom-pom` import. Compiler level is 21. LICENSE, NOTICE, CODEOWNERS and CLAUDE.md are byte-identical to `origin/main`.
3. Green on 4.0.0, plus a green `qqq-snapshot` profile	Met	I re-ran both locally (results below). The profile matches B1 and B3: it imports `qqq-bom-pom:${qqq.snapshot.version}` (default `4.1.0-SNAPSHOT`) and adds the Central snapshots repository.
4. Docker ITs fail (not skip) when `CI=true`	N/A	Neither module has Testcontainers, Docker, `Assumptions`, `@Disabled` or `@EnabledIf`.
5. No explicit qqq module versions	Met	`qqq-backend-core` and `qqq-backend-module-rdbms` have no `<version>`.

Verification I ran (worktree at `a73162b`)

mvn -B clean verify: BUILD SUCCESS.
mvn -B -U -Pqqq-snapshot clean verify: BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped.
dependency:list -pl qbit-geo-data-core: resolves qqq modules to 4.0.0 by default and to 4.1.0-SNAPSHOT with -Pqqq-snapshot.
CircleCI build 13 at a73162b: success. The "Keep package installation unattended" pre-step ran before "Install Java 21 and build tools". The commands block is identical to qbit-quick-search develop (checked with yq and diff), and all 5 jobs carry the pre-step. qbit-quick-search develop has already run mvn_publish with the same pre-step and it passed.
Checkstyle and coverage: the repo and the parent configure no checkstyle, and JaCoCo only generates a report (no check goal or thresholds). So neither can fail the build.
Global Constraints: the branch comes from develop and targets develop. No mvn install is listed. No secrets: I grepped the diff for password, secret, token, key and private-key patterns and found nothing. No release or publish actions.

Non-blocking notes

Merge method matters. Plan step 1 asks for a separate back-merge PR first. This PR carries the back-merge as its first commit instead, the same way B2 and B4 do. The repo allows squash and rebase merges, and develop has no branch protection. So whoever merges must pick "Create a merge commit". Otherwise main's three commits never become ancestors of develop, and the branches stay diverged. The PR body already says this. It is repeated here so it isn't missed at merge time.
Duplicate snapshot repository. qbit-build-parent:2.0.0 already declares central-portal-snapshots with the same URL (https://central.sonatype.com/repository/maven-snapshots/, snapshots only) for every build. The profile adds that URL a second time under a different id (sonatype-snapshots), so Maven may check the same repository twice, and a settings.xml mirror or server entry keyed on the parent's id won't apply to it. Reusing the id central-portal-snapshots would override the parent's entry instead of duplicating it. B1 and B3 use sonatype-snapshots too, so either leave it alone for consistency or fix it across all the qbits in one pass.
How the profile takes precedence. Maven keys managed dependencies by groupId:artifactId:type. The profile's qqq-bom-pom import therefore replaces the parent's 4.0.0 import during inheritance, rather than being "ahead of" it. Only the snapshot BOM is imported, which is the intended result. This affects only the wording in the PR body. The pom comment is accurate.
CLAUDE.md (from main) is stale after this merge. It says "main and develop have diverged", and its vault links use Windows R:/ paths. It came in unchanged from main, which is correct for a back-merge, so any update belongs in a follow-up.
Pre-existing, out of scope (already noted in the PR): the pom <licenses> block still says AGPL-3.0 while the incoming LICENSE is Apache-2.0 (an owner decision under the plan's licensing rule). The child junit-bom 5.10.0 import still overrides the parent's 6.0.1. JaCoCo is 0.8.10.
The built-in security-review skill couldn't run from the orchestrator's working directory, which is not a git repo. I did the manual pass above instead. The only security-relevant changes are an opt-in, HTTPS, snapshots-only repository and a CI step that writes a needrestart config file.

## Review, round 1 (plan task B7, QRun-IO/qqq#769) ``` PR #3: build: re-pin to qbit-build-parent 2.0.0, add qqq-snapshot profile Tier: Deep (2 risk signals) Sized: 289/3 across 8 files (202 of the additions are LICENSE) Risk signals: build/release (.circleci/config.yml), dependency/build change (pom.xml parent and repository) Routing to: pr-review-toolkit:review-pr (code-reviewer and comment-analyzer passes; no test, error-handling or type changes), plus a manual security pass ``` **Verdict: approve. No blocking issues.** ### B7 requirements | Step | Status | Evidence | |---|---|---| | 1. Back-merge `main` into `develop` | Met, but inside this PR (see note 1) | `819b3da` is a two-parent merge (`b9eaa6c` + `ebb950f`). Compared with `develop`, it adds only CODEOWNERS, CLAUDE.md, LICENSE and NOTICE. Compared with `main`, it keeps only develop's `.gitignore`, the `.claude/settings.local.json` removal and the `0.2.0-SNAPSHOT` revision. Nothing was lost. | | 2. Parent 2.0.0, Java 21, no shadowing qqq BOM, licenses untouched | Met | Parent is `qbit-build-parent:2.0.0`. The child poms have no `qqq-bom-pom` import. Compiler level is 21. LICENSE, NOTICE, CODEOWNERS and CLAUDE.md are byte-identical to `origin/main`. | | 3. Green on 4.0.0, plus a green `qqq-snapshot` profile | Met | I re-ran both locally (results below). The profile matches B1 and B3: it imports `qqq-bom-pom:${qqq.snapshot.version}` (default `4.1.0-SNAPSHOT`) and adds the Central snapshots repository. | | 4. Docker ITs fail (not skip) when `CI=true` | N/A | Neither module has Testcontainers, Docker, `Assumptions`, `@Disabled` or `@EnabledIf`. | | 5. No explicit qqq module versions | Met | `qqq-backend-core` and `qqq-backend-module-rdbms` have no `<version>`. | ### Verification I ran (worktree at `a73162b`) - `mvn -B clean verify`: BUILD SUCCESS. - `mvn -B -U -Pqqq-snapshot clean verify`: BUILD SUCCESS, 28 tests, 0 failures, 0 errors, 0 skipped. - `dependency:list -pl qbit-geo-data-core`: resolves qqq modules to `4.0.0` by default and to `4.1.0-SNAPSHOT` with `-Pqqq-snapshot`. - CircleCI build 13 at `a73162b`: success. The "Keep package installation unattended" pre-step ran before "Install Java 21 and build tools". The `commands` block is identical to qbit-quick-search `develop` (checked with `yq` and `diff`), and all 5 jobs carry the pre-step. qbit-quick-search `develop` has already run `mvn_publish` with the same pre-step and it passed. - Checkstyle and coverage: the repo and the parent configure no checkstyle, and JaCoCo only generates a report (no `check` goal or thresholds). So neither can fail the build. - Global Constraints: the branch comes from `develop` and targets `develop`. No `mvn install` is listed. No secrets: I grepped the diff for password, secret, token, key and private-key patterns and found nothing. No release or publish actions. ### Non-blocking notes 1. **Merge method matters.** Plan step 1 asks for a separate back-merge PR first. This PR carries the back-merge as its first commit instead, the same way B2 and B4 do. The repo allows squash and rebase merges, and `develop` has no branch protection. So whoever merges must pick **"Create a merge commit"**. Otherwise `main`'s three commits never become ancestors of `develop`, and the branches stay diverged. The PR body already says this. It is repeated here so it isn't missed at merge time. 2. **Duplicate snapshot repository.** `qbit-build-parent:2.0.0` already declares `central-portal-snapshots` with the same URL (`https://central.sonatype.com/repository/maven-snapshots/`, snapshots only) for every build. The profile adds that URL a second time under a different id (`sonatype-snapshots`), so Maven may check the same repository twice, and a `settings.xml` mirror or server entry keyed on the parent's id won't apply to it. Reusing the id `central-portal-snapshots` would override the parent's entry instead of duplicating it. B1 and B3 use `sonatype-snapshots` too, so either leave it alone for consistency or fix it across all the qbits in one pass. 3. **How the profile takes precedence.** Maven keys managed dependencies by groupId:artifactId:type. The profile's `qqq-bom-pom` import therefore *replaces* the parent's 4.0.0 import during inheritance, rather than being "ahead of" it. Only the snapshot BOM is imported, which is the intended result. This affects only the wording in the PR body. The pom comment is accurate. 4. **CLAUDE.md (from `main`) is stale after this merge.** It says "main and develop have diverged", and its vault links use Windows `R:/` paths. It came in unchanged from `main`, which is correct for a back-merge, so any update belongs in a follow-up. 5. **Pre-existing, out of scope (already noted in the PR):** the pom `<licenses>` block still says AGPL-3.0 while the incoming LICENSE is Apache-2.0 (an owner decision under the plan's licensing rule). The child `junit-bom` 5.10.0 import still overrides the parent's 6.0.1. JaCoCo is 0.8.10. 6. The built-in `security-review` skill couldn't run from the orchestrator's working directory, which is not a git repo. I did the manual pass above instead. The only security-relevant changes are an opt-in, HTTPS, snapshots-only repository and a CI step that writes a needrestart config file.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qbit-geo-data#3