[jwrosewell]

Problem

No Pipeline developer example and no Location example ended with a "Find out more" section, found in the audit of the examples on 13 November. 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.

#133 does this for the Device Detection and IP Intelligence examples. This draft does the rest of the console examples, the five Pipeline developer examples that have a main method and the two Location shell examples.

What changed and why

Line numbers are at this head, cfd047a.

• The Pipeline developer examples. Each Main of the flow element, on-premise engine, cloud engine, usage sharing and 51Did examples gains writeFindOutMore, which main calls after the example has run, so the run method that the documentation shows is unchanged. The section lists the example's own documentation page and the documentation page of the feature it shows, 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 this repository and the specifications repository. The 51Did example lists the Identifiers page and the contact page, as "Ask about 51Did", in place of a feature page. For example, the flow element example's is in Main.java lines 73 to 98.
• The Location examples. A new FindOutMore in geo-location.shell.examples writes the section, with the example's documentation page, the Location page and this repository. cloud/GettingStarted.java lines 121 to 124 and CombiningServices.java lines 182 to 185 call it as the last line of main, so the section also ends the output when no resource key is set and the example only says how to get one.
• The pages. All eleven 51degrees.com addresses the change adds were fetched on 14 November at 09:38 UTC, and each answered with the title of the page it names, for example "51Degrees API Documentation: Simple custom flow element" for the flow element example and "Contact us | 51Degrees" for the contact page. The documentation answers an unknown page with its introduction, so the title, not the status, is what shows each page exists. The campaign tag lint passed on the head.

What it releases

The five developer examples and geo-location.examples are published packages. Under the version per package change (#63) a change to any of them alone releases nothing, because its ci/packages.json gives each example package an Ignore glob over its whole folder, pipeline/pipeline.developer-examples/** for the developer examples and location/geo-location.shell.examples/** for the Location ones, as its ci/packages.ps1 says ("give an Ignore glob over their whole folder, so a change to one releases nothing"). All six are in Monday's plan anyway, as dependants of changed packages (Publish dry run 43559110241 on #63), so this draft adds no package to the release.

Tests

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

Part	Test commit	Change commit	Red	Green
Pipeline developer examples	6769325e	d1606b3e	43562061075	43562081101
Location examples	4316f5f8	cfd047a1	43560233540	43560242349

• FindOutMoreTests in each of the five developer example modules runs Main.main, and checks that the section follows the example's own output, has a closing rule, lists exactly two 51degrees.com pages, each carrying the five campaign tags in order, and lists this repository.
• FindOutMoreTests in geo-location.shell.examples runs GettingStarted and CombiningServices with no resource key and makes the same checks.

Each red and green ran on ubuntu-latest on a throwaway branch holding the commit and a temporary workflow that ran mvn -Pdev -pl <the modules> -am test with only the named tests.

• Red, developer examples, on 6769325 (tmp/java-fomp-red). The five FindOutMoreTests failed and the five ExampleTests classes passed, 14 tests.
• Green, developer examples, on d1606b3 (tmp/java-fomp-green). All 19 passed, the five FindOutMoreTests and the 14 tests of the five ExampleTests classes.
• Red, Location, on 4316f5f (tmp/java-fomloc-red). Both tests failed.
• Green, Location, on cfd047a (tmp/java-fomloc-green). Both passed.

Full build

Run 43563430562 built cfd047a merged with rc (6e03a25) 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. The six new test classes passed in all nine jobs. Each of its ten Setting 'PullRequestSha' lines names cfd047a, and its Configure job printed "Left out 6 macOS entries".

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. The branch starts from rc at 6e03a25. A trial merge with rc at ceab088, which has since taken #27, #124 and #43, was clean on 14 November at 09:30 UTC. #115 changes the configuration page address on two lines of each Location example, away from the lines this draft adds.

What remains

• The Location MVC and servlet web examples 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.
• The Location shell examples still take a resource key only by editing the source, which #151 also covers.