[jwrosewell]

Problem

This draft closes two gaps from the audit of the deferred work and the examples, DX-node-26 and DX-node-27. On rc at 758fea8 the examples did not end with a "Find out more" section, which is the part of an example that gives the person running it somewhere to go next.

• DX-node-26. None of the 41 console examples printed the section. Device Detection's on-premise getting started example, for example, ends with the Enterprise note and the data file line (gettingStarted.js lines 157 to 161).
• DX-node-27. Ten web examples had no section on their page. They are Device Detection cloud gettingstarted-web/index.pug and useragentclienthints-web/index.pug, Device Detection on-premise useragentclienthints-web/index.pug, IP Intelligence cloud gettingstarted-web/index.pug, IP Intelligence on-premise gettingstarted-web/index.pug, mixed/gettingstarted-web/index.pug and mixed/gettingstarted-api/gettingStarted.js, location/examples/webIntegration.js, pipeline/fiftyone.pipeline.core/examples/customFlowElements/clientSideEvidenceFlowElement.js and pipeline/fiftyone.pipeline.engines/examples/onPremiseFlowElement.js.

Three pages already ended with the section. Two of them did not follow the pattern the others use.

• The Device Detection on-premise web page (index.pug lines 149 to 170) is the model this draft copies.
• The IP Intelligence cloud mixed web page (index.pug lines 140 to 151) gave the Device Detection folder but not the IP Intelligence folder it belongs to.
• The 51Did creator context page (page.html lines 142 to 152) tagged its links with utm_content=fiftyone.pipeline.did-creator-context-web-page.html, which leaves examples out of the file's path, where every other example in the repository names its file by its full path below the product folder.

What the specification and the rules say

The specification's examples pages at c8128ca4 do not mention a "Find out more" section. What they say about the links an example writes, and about how an example ends, is this.

• Device Detection, required-examples.md lines 105 to 113: "Where the data file in use has no value for one of them, the example says that the Property needs the Enterprise Data File, rather than leaving it out or showing a default value, and once in its output gives a link to the 51Degrees contact page to ask for a copy. The link the example writes carries utm_source=code, utm_medium=example, the language repository's name as utm_campaign and the example's file as utm_content, so that an enquiry can be traced to the example that prompted it."
• The same page, lines 115 to 117: "An example whose purpose needs the Enterprise Data File or a License Key, such as one that updates the data file, explains that when it runs with the Lite Data File, gives the same link, and completes without failure."
• IP Intelligence, required-examples.md lines 80 to 91: "Examples follow the device detection rules for on-premise examples."
• The pipeline page says nothing about the links an example writes.

The section itself comes from 51Degrees' rule for examples, which is that every demo and example ends with a clearly separated "Find out more" section, giving the relevant engine repositories as bare addresses and 51degrees.com pages tagged with exactly five parameters in this order: utm_source, utm_medium, utm_campaign (the repository's name), then utm_content and utm_term as lowercase slugs, with the term at most 60 characters. common-ci's scripts/utm-lint.ps1 checks those tags. The rules for this work add that the section prints at every clean end of an example, including an early end with no resource key, no data file, or a paid file or licence key needed, and that this applies to every example, including those that use no 51Degrees data. Each link to 51degrees.com in a section carries utm_content naming the example's file, as the specification asks of the contact link, and a utm_term starting find-out-more.

What changed

1. The console examples. Each of the 41 holds a FIND_OUT_MORE constant with its own links, so a person reading one example sees all of it, and prints it at every clean end. The section is a blank line, a rule of 79 equals signs, the heading Find out more:, then one line per link, each a tab, a label and an address. Where an example's main block calls run, it now prints the section once run has finished without an error, which covers an early return inside run as well as the normal end. Where an example stops early in its main block, for want of a resource key, a data file or a licence key, it prints the section after its message. The performance examples print it at the end of their FinishProcessing handler, the automatic update examples after their message with no licence key and just before they stop themselves, and the pipeline examples at the end of their last callback. The layout follows the Python draft for the same work, 51degrees-python#127.
2. What each section gives. Every section gives this API's folder in the repository. An on-premise example adds the engine repository, https://github.com/51Degrees/51degrees-cxx. Device Detection, IP Intelligence and location examples add the Pipeline API folder, the product's documentation page, the resource keys page for a cloud example, the pricing page and the contact page. The mixed examples give both the IP Intelligence and the Device Detection folders and documentation pages. The pipeline examples give the documentation page for what each one shows (custom flow elements, client-side evidence, result caching, usage sharing or what a 51Did is) and the contact page, and the 51Did example also gives https://github.com/51Degrees/specifications.
3. The web examples. The six pug pages that had no section end with one built like the Device Detection on-premise page. The location web example, and the two custom flow element examples, add the same links as HTML at the end of the page they write, and the location web example prints the console section when it stops for want of a resource key. The local cloud API example (mixed/gettingstarted-api/gettingStarted.js) serves JSON, so it prints the section on the console once it is listening, or when it cannot start for want of a data file.
4. The pages that already had a section. The IP Intelligence cloud mixed page now gives https://github.com/51Degrees/51degrees-node/tree/main/ip-intelligence as "This API". The 51Did creator context page tags its two links with utm_content=fiftyone.pipeline.did-examples-creator-context-web-page.html.
5. The update data file examples. With a licence key, run returned once it had built the pipeline, while the two updates carried on, so a section printed when run settled would have come before "Finished example". run now returns a promise that settles once the example has finished, and the main block prints the section then. No test calls run with a key.

Nothing else changes in what an example does with no key or no data file. Five kinds of end stop with an error and a non-zero exit status, so they are not clean ends and print no section. They are the cloud web examples, which throw at start-up with no resource key (DX-node-30), the on-premise web examples, the match metrics and performance examples and the automatic update examples when their data file is missing, which throw, and the 51Did creator context demo, which exits with status 1 with no resource key (DX-node-30).

Tests

Tests first, in 23bef0b and 7695853, then the change in aeb5548. 0e574c6 merges rc at 076bc17, which brought #104's tests that run the pipeline examples, and 1fd34e7 adds the section to what those tests check.

• A new findOutMore.test.js in each product folder, being device-detection/fiftyone.devicedetection/tests, ip-intelligence/fiftyone.ipintelligence/tests, location/tests and pipeline/fiftyone.pipeline.core/tests. Each reads every example's source and fails for each one that lacks the heading, the link to this API's folder, or a 51degrees.com link tagged utm_source=code&utm_medium=example&utm_campaign=51degrees-node&utm_content=<the file's path below the product folder>&utm_term=find-out-more..., naming what is missing. Each also fails when a .js, .pug or .html file in an examples folder is listed neither as an example nor as a helper, so a new example cannot be added without the section. The Device Detection and IP Intelligence tests also run each cloud console example in its own process with no resource key, which ends it before it calls the cloud service, and check that what it prints ends with the section.
• 7695853 changes only how those source checks report a failure. The first version compared the whole file with each expected text, so a failure printed the file, and the IP Intelligence metrics.js example holds NUL characters that the test result file cannot carry (the red full build below could not read its result files). The checks are the same.
• Both examplesWithoutSettings.test.js files check that every console example they run ends with the section, and that each web page they fetch has it after its results.
• location/examples/examples.test.js checks that the section follows the lines each location example prints, with or without a resource key.
• The four pipeline example tests that Run the pipeline examples in their tests, and serve the star sign pages when a value is not yet known #104 added or rewrote, fiftyone.pipeline.core/examples/examples.test.js, fiftyone.pipeline.engines/tests/engines.examples.test.js, fiftyone.pipeline.did/tests/fodIdExample.test.js and fiftyone.pipeline.engines.fiftyone/tests/usageSharingExample.test.js, check that each console example's output ends with the section and that each star sign page has it after its content. The simple flow element test, which expected the example to print only libra, now expects libra as the only line before the section.

How it was verified

Run	What	Commit	Result
43554888701	The four new tests and location/examples/examples.test.js on Ubuntu with Node.js 24, no resource key, with the tests only	514b07b8 (23bef0b and a throwaway workflow, on rc 758fea8)	Failed as expected, 67 failed and 5 passed of 72. The 5 are the four checks that every example is listed and the Device Detection on-premise web page, which already had the section.
43555875199	The same, with the change	86f71b0 (the change as first committed, 05687e1, and the throwaway workflow)	Passed, 72 of 72. npm run lint 0 errors (189 warnings, as on the red run), and the link lint "clean for campaign '51degrees-node'". The configurator example with no resource key printed its message, then the section.
43556288985	Full build of this draft with the first test commit as its head, without macOS	23bef0b	Failed as expected. In each of the six jobs the unit tests reported 60 failed, 2 skipped and 1371 passed, the 60 being the source checks of the Device Detection, IP Intelligence and pipeline tests. A failed unit test step ends the job, so the no-settings tests did not run in this build, which is why the next run exists.
43558707871	Both native modules built, the free data files fetched with cxx/data/get-data-files.sh, then the four new tests, location/examples/examples.test.js and both examplesWithoutSettings.test.js, on Ubuntu with Node.js 24, with the tests only	317399d (7695853 and a throwaway workflow)	Failed as expected, 92 failed and 6 passed of 98. 25 of the 26 no-settings tests failed, the one that passed being the Device Detection on-premise web page, which already had the section.
43558716785	The same, with the change	0a8f120 (aeb5548 and the throwaway workflow)	Passed, 98 of 98, lint 0 errors, link lint clean. The Device Detection on-premise getting started example on the free data file ended with its data file line, then the section.
43559421250	Full build of this draft at aeb5548, without macOS	aeb5548	Superseded. Five jobs passed. Ubuntu_Node_22 failed one test, "custom flowElements 1", which #104 added to rc at 05:22 while this build waited for runners. It expected the simple flow element example to print only libra, so it met the new section. That is why 0e574c6 and 1fd34e7 exist.
43564090307	The four pipeline example tests on Ubuntu with Node.js 24, with 1fd34e7's test changes on rc 076bc17 and no example changed	2a35bcf	Failed as expected, 9 of 9.
43564099258	The same tests on this draft's head	94323fd (1fd34e7 and the throwaway workflow)	Passed, 9 of 9, lint 0 errors, link lint clean.
43564688561	Full build of this draft's head, without macOS, with rc at 076bc17	1fd34e7	Passed. Configure printed "Left out 2 macOS entries", and all seven Setting 'PullRequestSha' lines (Configure and the six Build and Test jobs) name 1fd34e7. In each of the six jobs (Ubuntu and Ubuntu ARM with Node.js 22 and 24, Windows with Node.js 22 and 24) the unit tests reported 2 skipped and 1447 passed, and the integration tests 4 skipped and 138 passed. The four new findOutMore.test.js, both examplesWithoutSettings.test.js, location/examples/examples.test.js and the four pipeline example tests are among the suites that passed in each job. The Selenium contract passed, 9 of 9 twice.

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.

Two earlier runs of the pipeline throwaway branches, 43564050754 and 43564059590, ran the wrong workflow file and are not evidence of anything. Every throwaway branch is deleted.

Package files

No package code changes, only examples and tests. The Device Detection and IP Intelligence packages list their files (*.js and types, with build for on-premise), which leaves out examples and tests, as #95 found with npm pack --dry-run, and since #106 fiftyone.pipeline.core lists *.js, types and its one template. fiftyone.geolocation, fiftyone.pipeline.engines, fiftyone.pipeline.engines.fiftyone and fiftyone.pipeline.did have no files list, so their packages carry their examples and tests folders and this change reaches them.

Merge order

This head contains rc at 076bc17. git merge-tree of this head with the heads of #87 (74a087a), #37 (b239089) and #98 (a8fb0e4) reports no conflict. #87 changes the configuration page address in several of the same examples, with at least one unchanged line between its lines and this draft's. In the six automatic update examples this draft adds console.log(FIND_OUT_MORE); directly above process.exit(1);, so a draft that changes that line will conflict with this one there, and the resolution keeps both lines.

What remains

• The ends that stop with an error, listed under "What changed", print no section. How a cloud example should end with no resource key waits on the question on cloud examples (DX-node-30 and DX-node-38).