Skip to content

Examples that build from a fresh clone, checked in CI - #192

Merged
ben51degrees merged 2 commits into
rcfrom
remote/java-fresh-clone
Nov 19, 2026
Merged

ben51degrees merged 2 commits into
rcfrom
remote/java-fresh-clone

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

The problem

Since #175, the tests in examples/device-detection imported TestFileUtils and TestKeyUtils from device-detection.shared's src/test. A fresh clone builds the examples against the published packages, whose 4.5.130 tests jar has neither class, so mvn -pl console -am package -DskipTests in examples/device-detection failed at GettingStartedOnPremTest.java:[26,51]. #187 (343baac) fixed that build, and rc passes from a fresh clone. Nothing stops the same failure coming back.

What the specification says

required-examples.md lines 91 to 97 at d79bbe3b says

Examples MUST run out of the box with the free data files. Given no arguments or settings, an example uses the Lite Data File, 51Degrees-LiteV4.1.hash, which the data repository links in its device-detection folder. An example looks for the file and, when it is missing, downloads it with the data repository's get-data-files script, so a fresh clone of a language repository runs every example with nothing set.

The new step guards the build half of that, so an example that cannot build from a fresh clone fails in CI.

The change

f17fd53 adds a step to the Examples from a fresh clone workflow (.github/workflows/examples-fresh-clone.yml). On Ubuntu it builds every example module, the web examples too, with its tests compiled, against only the published packages, so a test that uses a class the published packages lack fails there. It runs after the asset cache is saved, so the other systems still get the data file, and it does not run the tests, which the pull request build runs. AGENTS.md describes the new step.

rc has since made -ExpectDownload a switch of ci/run-fresh-clone-example.ps1 (#196), so the script runs by hand with pwsh -File as AGENTS.md says, and this draft's step does not call the script.

The runs

  • Red: run 43897661762, this workflow at 20f9089 (Specification conformance, 51degrees-java, section 15 #175, the parent of Build the Device Detection example tests from a fresh clone #187): the device-detection job on Ubuntu fails at its console build step, "Build the console examples against the published packages", with the first error GettingStartedOnPremTest.java:[26,51] cannot find symbol, so the new step does not run there. The new step widens what the workflow builds, to every example module with its tests.
  • Green: run 43887891837, the pull request run at f17fd53: the new step passes for device-detection and ip-intelligence on Ubuntu, and the console builds pass on Ubuntu and Windows.
  • A fresh clone on macOS (Intel) with an empty local Maven repository, so only the published packages were used: the build and ci/run-fresh-clone-example.ps1 pass for both products at f17fd53 and at rc 81e3d4a, and every com.51degrees artifact resolved at 4.5.130. At 20f9089 the device-detection build fails at GettingStartedOnPremTest.java:[26,51], and ManualDataUpdateTest, MetadataOnPremTest and OfflineProcessingTest fail the same way.
  • Full build: run 43900202044 on tmp/pr-matrix-192-f17fd53 (workflow commit 67e3d14 on rc 81e3d4a) built f17fd53, as the Setting 'PullRequestSha' line of its Ubuntu Java 8 job names. Configure, all nine Build and Test jobs (Ubuntu x64 with Java 8, 11, 17 and 21, Ubuntu arm64 with Java 17, and Windows with Java 8, 11, 17 and 21) and Complete passed. macOS was left out of that build. This change touches CI and AGENTS.md only, so the workflow's own runs are the tests of what it touches, and the build above is extra.

Changes at this head

The previous head, f17fd53, no longer merged into rc, where #196 had rewritten the same paragraph of AGENTS.md to say how to run the fresh clone check by hand. One commit follows it.

  • 9b1fa72e merges rc 3bb6e71 in. One conflict, in AGENTS.md, where both sides are kept, this draft's sentence that the Ubuntu job then builds every example module with its tests compiled, followed by rc's sentence on running the check by hand with pwsh -File and -ExpectDownload. The workflow merged with no conflict, and this draft's step still comes after the data file is saved for the other systems. The commit adds no test, so it has no red.
  • Green, 9b1fa72: fresh clone run 44463861742. In both Ubuntu jobs the console build, the getting started example and this draft's step, "Build every example and its tests against the published packages", passed, and the Windows jobs passed. The first attempt of the IP Intelligence Ubuntu job stopped before building, when Maven Central did not serve the POM of maven-pmd-plugin 3.28.0 to that runner, which the Device Detection job of the same run had resolved, and the job passed when run again. CI script tests run 44463861716 passed on Ubuntu and Windows, and every other check on 9b1fa72 passed.

What remains

Nothing in this draft. #148 also changes .github/workflows/examples-fresh-clone.yml and AGENTS.md, in other lines, and a trial merge of the two heads is clean.

Before you upgrade

Nothing changes in the packages. This adds a CI step only.

The fresh-clone workflow built only the console examples, with their
tests compiled. A web example test that used a class the published
packages lack would not have failed it. The Ubuntu job now builds every
example module with its tests compiled, after it has saved the data file
for the other systems.
@jwrosewell jwrosewell added the remote-conformance Specification conformance work from the remote packs label Nov 16, 2026
@jwrosewell jwrosewell changed the title Specification conformance, 51degrees-java, examples that build from a fresh clone Examples that build from a fresh clone, checked in CI Nov 18, 2026
…heck

One conflict, in AGENTS.md, where rc says how to run the fresh clone check
by hand with -ExpectDownload as a switch, and this branch says the Ubuntu
job then builds every example module with its tests compiled. Both are
kept, this branch's sentence first, then rc's sentence on running the
check by hand. The workflow merged with no conflict, and this branch's step
still comes after the data file is saved for the other systems.
@ben51degrees
ben51degrees marked this pull request as ready for review November 19, 2026 17:18
@ben51degrees
ben51degrees merged commit 5269b68 into rc Nov 19, 2026
11 of 12 checks passed
@ben51degrees
ben51degrees deleted the remote/java-fresh-clone branch November 19, 2026 17:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

remote-conformance Specification conformance work from the remote packs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants