QRun-IO/qqq-all
3
0 Fork 0
Code Issues 5 Pull Requests 4 Actions Packages Projects Releases Wiki Activity

build: bootstrap repo, Maven reactor, and CircleCI (QRun-IO/qqq-all#2) #12

Merged
KofTwentyTwo merged 6 commits from feature/GH-2-bootstrap into develop 2026-09-26 06:50:44 +00:00
Conversation 1 Commits 6 Files Changed 15
+665
KofTwentyTwo commented 2026-09-26 00:30:14 +00:00 (Migrated from github.com)
Copy link
Copy source

Pull Request

Description

What does this PR do?
Bootstraps the repo (plan task C1): community files, GitHub templates, the Maven reactor, and CircleCI build plus unit tests through qqq-orb.

  • README.md: short overview, status, modules, build command. The quick start and feature tour come in C8.
  • NOTICE, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md: adapted from qqq for this repo (Apache-2.0, QRun-IO links, qrun.io contacts, emoji removed). SECURITY.md states the demo-only scope and that demo credentials are local-only.
  • .github/: bug, feature, and docs issue templates, config.yml (blank issues off; framework issues routed to QRun-IO/qqq), and the PR template. All adapted from qqq.
  • .gitignore: qqq's, without the duplicated Eclipse block.
  • pom.xml: com.kingsrook.qqq:qqq-all-parent:${revision}, where revision is 4.1.0-SNAPSHOT. It sets Java 21 (maven.compiler.release), Apache-2.0/scm/developers metadata, and modules qqq-all-bom (pom) and qqq-all-app (jar), both empty. It declares the Central snapshot repository (https://central.sonatype.com/repository/maven-snapshots/, snapshots only, updatePolicy=always) for QQQ 4.1.0-SNAPSHOT, and uses flatten (resolveCiFriendliesOnly) the way qqq does. The orb's version step reads <revision>.
  • .circleci/config.yml: kingsrook/qqq-orb@0.6.5, workflow test_only running qqq-orb/mvn_test_only (java executor, Java 21) with qqq's configure-package-install pre-step. The Maven jobs are the same in orb 0.6.0 (qqq's pin) and 0.6.5.

Related Issue:
Closes #2
Part of #1

Type of Change

  • New Feature - Adds new functionality
  • Documentation Update - Updates documentation
  • Build / CI - Changes to the Maven build, CircleCI, compose, or image

Testing

How has this been tested?

  • Unit Tests: All unit tests pass (there are none yet; the modules are empty)
  • Manual Testing: Reactor build under local Maven 3.9.16 and CI's Maven 3.6.3; CircleCI config validated and processed

This change has no runtime behavior. The gates are the build and the CI config, each run red first, then green.

Test Commands:

# Red: before the reactor existed
mvn -B -f pom.xml verify
# -> exit 1: "POM file .../pom.xml specified with the -f/--file command line argument does not exist"

# Green: final gate on the committed tree
mvn -B clean -q && mvn -B verify
# -> BUILD SUCCESS: QQQ All, QQQ All - Stack BOM, and QQQ All - Reference Application all SUCCESS.
#    Only warning: "JAR will be empty" for qqq-all-app, expected until C3 adds sources.

# CI parity: Maven 3.6.3 (the Ubuntu 22.04 apt Maven the orb's install_java installs),
# with the orb's exact settings file and flags
mvn -s /tmp/.../mvn-settings.xml -T4 --no-transfer-progress compile   # -> BUILD SUCCESS
mvn -s /tmp/.../mvn-settings.xml -T4 --no-transfer-progress verify    # -> BUILD SUCCESS

# CircleCI config (circleci CLI 1.0.51453)
circleci config validate                     # before the file existed -> exit 2 (no config file)
circleci config validate --org gh/QRun-IO    # -> Config file at ".circleci/config.yml" is valid. (exit 0)
circleci config process --org gh/QRun-IO .circleci/config.yml
# -> job qqq-orb/mvn_test_only on ubuntu-2204:current (large). The unattended-install pre-step runs first,
#    then Install Java 21, checkout, Maven compile, Maven verify, and JaCoCo/test-result collection.

circleci config validate without --org fails with "Cannot find kingsrook/qqq-orb@0.6.5 in the orb registry". The orb is private, and the CLI cannot infer the org because this repo has no CircleCI project yet (see below).

Checklist

  • Code Style: Follows QQQ conventions (3-space POM indentation, as in qqq modules)
  • Tests: All tests pass
  • Documentation: README and community docs added
  • Secrets: No secrets committed; the CI job uses no context
  • Breaking Changes: None
  • Commit Messages: Follow conventional commit format
  • Self Review: Code has been reviewed by the author

Additional Information

Needs a maintainer (settings I did not change):

  • CircleCI project not set up. GET /api/v2/project/gh/QRun-IO/qqq-all returns "Project not found", so no pipeline will run on this PR until the project is followed in CircleCI. The private orb resolves for the gh/QRun-IO org.
  • Private vulnerability reporting is off for qqq-all (it is on for qqq). SECURITY.md links to it the same way qqq's does, so it needs enabling in repo settings. Otherwise I can drop the link and keep email only.

Decisions:

  • test_only runs on every branch push, including develop, because there is no publish workflow yet. C6 adds the GHCR publish on develop merges, and branch filters can be adjusted then.
  • No CircleCI context. The build reads only public artifacts. The snapshot repository id (central-portal-snapshots) does not match the orb's central/central-snapshots server ids, so no unset credentials are sent to it.
  • The plugin versions are pinned (resources 3.3.1, compiler 3.14.1, surefire 3.5.4, jar 3.4.2; the last three match qqq). CI's Maven 3.6.3 would otherwise default to compiler 3.1 and surefire 2.12.4, which predate maven.compiler.release and JUnit 5.
  • The snapshot updatePolicy is always, because the orb restores a cached ~/.m2 and does not pass -U, so same-day SNAPSHOTs could otherwise go stale.
  • The POMs have no license header comment. The sibling QRun-IO POM headers still carry stale AGPL text, and this repo is Apache-2.0 per LICENSE.
  • qqq-all-bom inherits the parent, as qqq-bom-pom does in qqq. C2 fills it, and C3 fills the app.
  • Out of scope: CODEOWNERS, dependabot, release notes config, checkstyle (there is no Java yet), and publish workflows.
  • README links to docs/design.md and docs/plan.md, which land with #11.

Dependencies added/removed: none (build plugins only).

# Pull Request ## Description **What does this PR do?** Bootstraps the repo (plan task C1): community files, GitHub templates, the Maven reactor, and CircleCI build plus unit tests through `qqq-orb`. - `README.md`: short overview, status, modules, build command. The quick start and feature tour come in C8. - `NOTICE`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`: adapted from qqq for this repo (Apache-2.0, QRun-IO links, `qrun.io` contacts, emoji removed). SECURITY.md states the demo-only scope and that demo credentials are local-only. - `.github/`: bug, feature, and docs issue templates, `config.yml` (blank issues off; framework issues routed to QRun-IO/qqq), and the PR template. All adapted from qqq. - `.gitignore`: qqq's, without the duplicated Eclipse block. - `pom.xml`: `com.kingsrook.qqq:qqq-all-parent:${revision}`, where `revision` is `4.1.0-SNAPSHOT`. It sets Java 21 (`maven.compiler.release`), Apache-2.0/scm/developers metadata, and modules `qqq-all-bom` (pom) and `qqq-all-app` (jar), both empty. It declares the Central snapshot repository (`https://central.sonatype.com/repository/maven-snapshots/`, snapshots only, `updatePolicy=always`) for QQQ 4.1.0-SNAPSHOT, and uses flatten (`resolveCiFriendliesOnly`) the way qqq does. The orb's version step reads `<revision>`. - `.circleci/config.yml`: `kingsrook/qqq-orb@0.6.5`, workflow `test_only` running `qqq-orb/mvn_test_only` (java executor, Java 21) with qqq's `configure-package-install` pre-step. The Maven jobs are the same in orb 0.6.0 (qqq's pin) and 0.6.5. **Related Issue:** Closes #2 Part of #1 ## Type of Change - [x] **New Feature** - Adds new functionality - [x] **Documentation Update** - Updates documentation - [x] **Build / CI** - Changes to the Maven build, CircleCI, compose, or image ## Testing **How has this been tested?** - [x] **Unit Tests**: All unit tests pass (there are none yet; the modules are empty) - [x] **Manual Testing**: Reactor build under local Maven 3.9.16 and CI's Maven 3.6.3; CircleCI config validated and processed This change has no runtime behavior. The gates are the build and the CI config, each run red first, then green. **Test Commands:** ```bash # Red: before the reactor existed mvn -B -f pom.xml verify # -> exit 1: "POM file .../pom.xml specified with the -f/--file command line argument does not exist" # Green: final gate on the committed tree mvn -B clean -q && mvn -B verify # -> BUILD SUCCESS: QQQ All, QQQ All - Stack BOM, and QQQ All - Reference Application all SUCCESS. # Only warning: "JAR will be empty" for qqq-all-app, expected until C3 adds sources. # CI parity: Maven 3.6.3 (the Ubuntu 22.04 apt Maven the orb's install_java installs), # with the orb's exact settings file and flags mvn -s /tmp/.../mvn-settings.xml -T4 --no-transfer-progress compile # -> BUILD SUCCESS mvn -s /tmp/.../mvn-settings.xml -T4 --no-transfer-progress verify # -> BUILD SUCCESS # CircleCI config (circleci CLI 1.0.51453) circleci config validate # before the file existed -> exit 2 (no config file) circleci config validate --org gh/QRun-IO # -> Config file at ".circleci/config.yml" is valid. (exit 0) circleci config process --org gh/QRun-IO .circleci/config.yml # -> job qqq-orb/mvn_test_only on ubuntu-2204:current (large). The unattended-install pre-step runs first, # then Install Java 21, checkout, Maven compile, Maven verify, and JaCoCo/test-result collection. ``` `circleci config validate` without `--org` fails with "Cannot find kingsrook/qqq-orb@0.6.5 in the orb registry". The orb is private, and the CLI cannot infer the org because this repo has no CircleCI project yet (see below). ## Checklist - [x] **Code Style**: Follows QQQ conventions (3-space POM indentation, as in qqq modules) - [x] **Tests**: All tests pass - [x] **Documentation**: README and community docs added - [x] **Secrets**: No secrets committed; the CI job uses no context - [x] **Breaking Changes**: None - [x] **Commit Messages**: Follow conventional commit format - [x] **Self Review**: Code has been reviewed by the author ## Additional Information **Needs a maintainer (settings I did not change):** - **CircleCI project not set up.** `GET /api/v2/project/gh/QRun-IO/qqq-all` returns "Project not found", so no pipeline will run on this PR until the project is followed in CircleCI. The private orb resolves for the `gh/QRun-IO` org. - **Private vulnerability reporting is off** for qqq-all (it is on for qqq). SECURITY.md links to it the same way qqq's does, so it needs enabling in repo settings. Otherwise I can drop the link and keep email only. **Decisions:** - `test_only` runs on every branch push, including `develop`, because there is no publish workflow yet. C6 adds the GHCR publish on develop merges, and branch filters can be adjusted then. - No CircleCI context. The build reads only public artifacts. The snapshot repository id (`central-portal-snapshots`) does not match the orb's `central`/`central-snapshots` server ids, so no unset credentials are sent to it. - The plugin versions are pinned (resources 3.3.1, compiler 3.14.1, surefire 3.5.4, jar 3.4.2; the last three match qqq). CI's Maven 3.6.3 would otherwise default to compiler 3.1 and surefire 2.12.4, which predate `maven.compiler.release` and JUnit 5. - The snapshot `updatePolicy` is `always`, because the orb restores a cached `~/.m2` and does not pass `-U`, so same-day SNAPSHOTs could otherwise go stale. - The POMs have no license header comment. The sibling QRun-IO POM headers still carry stale AGPL text, and this repo is Apache-2.0 per `LICENSE`. - `qqq-all-bom` inherits the parent, as `qqq-bom-pom` does in qqq. C2 fills it, and C3 fills the app. - Out of scope: CODEOWNERS, dependabot, release notes config, checkstyle (there is no Java yet), and publish workflows. - README links to `docs/design.md` and `docs/plan.md`, which land with #11. **Dependencies added/removed:** none (build plugins only).
KofTwentyTwo commented 2026-09-26 00:36:18 +00:00 (Migrated from github.com)
Copy link
Copy source

Review, round 1 (task C1): approve. No blocking issues.

All C1 deliverables are present: community files, .github issue and PR templates, .gitignore, the reactor with qqq-all-bom and qqq-all-app, and CircleCI through qqq-orb. What I checked:

  • mvn -B clean verify passes on Maven 3.9.16.
  • The orb's exact commands (-s mvn-settings.xml -T4 --no-transfer-progress compile, then verify) pass on Maven 3.6.3, and the pinned compiler 3.14.1 and surefire 3.5.4 are the versions that run.
  • -Drevision=9.9.9-review is written into all three flattened POMs.
  • The CircleCI config validates with orb v0.6.5 inlined from the tagged source. I have no CircleCI token, so I couldn't run it with --org. In the processed job, the unattended-install pre-step runs before Java 21, checkout, compile, and verify.
  • gitleaks found no leaks in the 6 commits.
  • The snapshot repo serves qqq-backend-core:4.1.0-SNAPSHOT.

Before merge (maintainer settings):

  1. Follow QRun-IO/qqq-all in CircleCI and get one green run on this PR. Until then, "build plus unit tests on PRs" is only config.
  2. Turn on private vulnerability reporting. The API returns enabled: false, so the link on SECURITY.md line 24 goes to a dead page.
  3. Merge #11 first. Until then, the README links to docs/design.md and docs/plan.md are broken.

Non-blocking:
4. CONTRIBUTING.md line 12 says Maven 3.8+, but CI builds with 3.6.3 and the POM comment says so. The two should agree.
5. For C3: this PR has no JaCoCo or checkstyle, so the orb's JaCoCo collection step does nothing. When Java lands, add JaCoCo with qqq's coverage thresholds, and checkstyle with an Apache-2.0 checkstyle/license.txt. qqq's checkstyle Header module enforces AGPL text, so the Global Constraint "license header copied from a neighboring file" conflicts with this repo's license. That needs a decision before C3. Leaving the POMs without a header is right for now.

**Review, round 1 (task C1): approve. No blocking issues.** All C1 deliverables are present: community files, `.github` issue and PR templates, `.gitignore`, the reactor with `qqq-all-bom` and `qqq-all-app`, and CircleCI through `qqq-orb`. What I checked: - `mvn -B clean verify` passes on Maven 3.9.16. - The orb's exact commands (`-s mvn-settings.xml -T4 --no-transfer-progress compile`, then `verify`) pass on Maven 3.6.3, and the pinned compiler 3.14.1 and surefire 3.5.4 are the versions that run. - `-Drevision=9.9.9-review` is written into all three flattened POMs. - The CircleCI config validates with orb v0.6.5 inlined from the tagged source. I have no CircleCI token, so I couldn't run it with `--org`. In the processed job, the unattended-install pre-step runs before Java 21, checkout, compile, and verify. - gitleaks found no leaks in the 6 commits. - The snapshot repo serves `qqq-backend-core:4.1.0-SNAPSHOT`. Before merge (maintainer settings): 1. Follow `QRun-IO/qqq-all` in CircleCI and get one green run on this PR. Until then, "build plus unit tests on PRs" is only config. 2. Turn on private vulnerability reporting. The API returns `enabled: false`, so the link on `SECURITY.md` line 24 goes to a dead page. 3. Merge #11 first. Until then, the README links to `docs/design.md` and `docs/plan.md` are broken. Non-blocking: 4. `CONTRIBUTING.md` line 12 says Maven 3.8+, but CI builds with 3.6.3 and the POM comment says so. The two should agree. 5. For C3: this PR has no JaCoCo or checkstyle, so the orb's JaCoCo collection step does nothing. When Java lands, add JaCoCo with qqq's coverage thresholds, and checkstyle with an Apache-2.0 `checkstyle/license.txt`. qqq's checkstyle `Header` module enforces AGPL text, so the Global Constraint "license header copied from a neighboring file" conflicts with this repo's license. That needs a decision before C3. Leaving the POMs without a header is right for now.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something isn't working
 dependencies
documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 epic
Epic tracking issue
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 question
Further information is requested
 secuurity
wontfix
This will not be worked on
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: QRun-IO/qqq-all#12