[jwrosewell]

Problem

Three gaps in the Device Detection and IP Intelligence examples, found in the audit of the examples on 13 November.

1. No example ended with a "Find out more" section. The only matches for "Find out more" on rc were the repository's README, a Javadoc line and the 51Did creator context page. The 51Degrees rule for examples is that every example ends with a clearly separated "Find out more" section that gives the person running it links to follow up, being the relevant repositories as plain addresses and 51degrees.com pages tagged with the campaign convention that common-ci's scripts/utm-lint.ps1 checks.
2. The Device Detection cloud web example named the cloud service over plain HTTP. 51Degrees-Cloud.xml line 28 at 30e48867 defaulted EndPoint to http://cloud.51degrees.com/api/v4.
3. The IP Intelligence on-premise and mixed web examples fell back to the Enterprise data file, which a fresh clone never has, when the free file could not be found or downloaded (51Degrees-OnPrem.xml line 32 and 51Degrees-Mixed.xml line 39 at 30e4886).

The specification says for Device Detection, in required-examples.md lines 91 to 93 at c8128ca4, "Examples MUST run out of the box with the free data files. Given no arguments or settings, an example uses the Lite Data File", and the IP Intelligence page names the free file, 51Degrees-LiteV41.ipi, in lines 73 and 74.

What changed and why

Line numbers are at e8b4ea4, and the files they name are the same at this head, 2e9b7f7.

• FindOutMore, in the shared module of each product (Device Detection and IP Intelligence), writes the section between two rules. It lists the product page, the pricing page and the documentation on 51degrees.com, each tagged with utm_source=code, utm_medium=example, utm_campaign=51degrees-java, the example as utm_content and find-out-more as utm_term, then the repositories. An on-premise example lists this repository, 51degrees-cxx and the data repository, and a cloud example this repository alone. link refuses a tag that is not a lower case slug, so a tag cannot break the convention. html gives the same section for a web page.
• Every console example with a main method, 13 for Device Detection and 13 for IP Intelligence, writes the section after its results and after the contact page link where it gives one, although a log line can still follow it, including the examples that stop early on a free data file, and IP Intelligence's CompareOnPrem and MetricsOnPrem when their fourth argument names no performance profile (2e9b7f70). OfflineProcessing writes it as YAML comments (Device Detection line 250, IP Intelligence line 281), so its output stays a valid YAML stream, and the examples whose writer closes standard output write it before that.
• Every web example that serves HTML ends its page with the section. The Device Detection on-premise and cloud pages get it from HtmlContentHelper lines 316 to 319, after the contact page banner, and the IP Intelligence on-premise, mixed, cloud and cloud mixed pages through a ${FIND_OUT_MORE} placeholder in their templates. The IP Intelligence getting-started.api example answers JSON only, so it has no page to end.
• HTTPS. The Device Detection cloud web example's options file defaults to https://cloud.51degrees.com/api/v4 (line 28).
• The free file. The IP Intelligence on-premise and mixed web examples' options files fall back to cxx/data/ip-intelligence/51Degrees-LiteV41.ipi (on-premise line 32, mixed line 39).

Every change is under the root examples folder, whose modules are not published packages, so under the version per package change (#63) it releases no package.

Tests

Tests first, each commit pair a test then its change.

Part	Test commit	Change commit	Red	Green
Console	99ac6847	e35c35d1	43536097278	43536097265
Web pages	2366f65e	b1945dbf	43536097496	the same green
Options files	b8b3b292	41981d1e	43536097311	the same green
Unknown profile	d25574f2	2e9b7f70	43583218975	43583231640

• FindOutMoreTest in each shared module has five tests (four from the console test commit and the HTML form from the web pages test commit), for the section's layout with its tagged links then the repositories, the cloud list of one repository, the YAML comment form, the HTML form, and link refusing a tag that is not a slug.
• FindOutMoreCoverageTest in each console module reads every source file under src/main/java and fails on any class with a main method that does not call FindOutMore.write, so a new example cannot leave it out.
• ExamplesWithoutSettingsTest in each console module now also checks the output of each example it runs with no settings. The section must come after the last link to the contact page and close with its rule. Log lines can follow the section, so the check does not ask that nothing comes after it. The IP Intelligence one also runs CompareOnPrem and MetricsOnPrem with a performance profile name that is not one.
• The web tests of each page that serves HTML check that it holds the section.
• CloudOptionsFileTest (Device Detection cloud web) checks the default endpoint is HTTPS, and OptionsFileTest (IP Intelligence on-premise and mixed web) checks the default data file is the Lite file.

Each red and green ran on ubuntu-latest on a throwaway branch holding the commit and a temporary workflow that runs the example modules' tests against the published 4.5.130 packages, each example finding or downloading its free file.

• Red, console, on 99ac684. FindOutMoreCoverageTest failed in both products, and ExamplesWithoutSettingsTest failed every example it runs, 6 of 6 for Device Detection and 9 of 9 for IP Intelligence, because none wrote the section. FindOutMoreTest passed its four tests at that commit.
• Red, web pages, on 2366f65 (console change included). GettingStartedWebOnPremTest failed in both products, with the console tests passing. The cloud page tests need a resource key, which the temporary workflow did not give, so they ran in the full build.
• Red, options files, on b8b3b29. CloudOptionsFileTest.defaultEndPoint_Https failed, and OptionsFileTest.defaultDataFile_FreeLiteFile failed in both IP Intelligence modules with "expected:<...51Degrees-[Lite]V41.ipi> but was:<...51Degrees-[EnterpriseIpi]V41.ipi>".
• Green, on 41981d1. Every test passed, including ExamplesWithoutSettingsTest, 6 of 6 and 9 of 9. GettingStartedWebMixedTest skipped its one test, which needs the cloud.
• Red, unknown profile, on d25574f, with Java 17 and only ExamplesWithoutSettingsTest. In IP Intelligence compare_UnknownProfile and metrics_UnknownProfile failed with "The output should have the 'Find out more' section after the link to the contact page", and the other 9 passed. Device Detection passed 6 of 6.
• Green, unknown profile, on 2e9b7f7. IP Intelligence passed 11 of 11 and Device Detection 6 of 6.

Full build

Run 43585242486 built 2e9b7f7 merged with rc (ceab088) on nine configurations, Ubuntu x64 with Java 8, 11, 17 and 21, Ubuntu arm64 with Java 17, and Windows with Java 8, 11, 17 and 21, and every job passed. ExamplesWithoutSettingsTest passed 6 of 6 for Device Detection and 11 of 11 for IP Intelligence in all nine jobs, and the cloud page tests that the throwaway runs could not run (GettingStartedWebCloudTest for each product, and the IP Intelligence GettingStartedWebCloudMixedTest and GettingStartedWebMixedTest) ran with the build's resource key and passed in all nine jobs, none skipped. Each of its ten Setting 'PullRequestSha' lines names 2e9b7f7, and its Configure job printed "Left out 6 macOS entries". The build of the earlier head, e8b4ea4, was run 43559426033, also green.

macOS was left out of this draft's full build under the 9 November decision. The rc head is built with macOS before it merges into main.

Base branch

rc (6e03a25), which was merged in at e8b4ea4 with a merge commit and no conflict, bringing #127, #128 and #130. A trial merge with rc at 1c99b72, which has since taken #27, #124, #43, #63, #83 and #115, was clean on 14 November at 12:00 UTC.

What remains

• The Location examples and the Pipeline developer examples end with the section in a separate draft, #134.
• The Location web pages and the client-side element web example have no test that runs them, and the Location pages need a resource key to show anything. #151 covers both.