Repository navigation
Run every example with no settings, and the usage sharing example under test - #173
Merged
Merged
Conversation
Answers device-detection-specification/required-examples.md line 13 at 706de1f0: There MUST be unit tests for examples, to verify that the example remains valid through various code changes. (EX-3)
…o its test shares nothing Answers device-detection-specification/required-examples.md line 13 at 706de1f0: There MUST be unit tests for examples, to verify that the example remains valid through various code changes. (EX-3)
…h clone Answers device-detection-specification/required-examples.md line 20 at 706de1f0: Those tests MUST include a run of each example with no arguments or settings, as someone would run it from a fresh clone, so that the run uses the free data files. (EX-4)
…set, and the on-premise web example can be started as its main starts it Answers device-detection-specification/required-examples.md line 20 at 706de1f0: Those tests MUST include a run of each example with no arguments or settings, as someone would run it from a fresh clone, so that the run uses the free data files. (EX-4)
Answers device-detection-specification/required-examples.md line 91 at 706de1f0: Examples MUST run out of the box with the free data files. (EX-6)
…erprise data file Answers device-detection-specification/required-examples.md line 91 at 706de1f0: Examples MUST run out of the box with the free data files. (EX-6)
Answers device-detection-specification/required-examples.md line 101 at 706de1f0: Examples MUST also show what only the Enterprise Data File can do, because the examples are where a developer first sees what the paid data files add. (EX-7)
…e Enterprise data file, and gives the contact page link once Answers device-detection-specification/required-examples.md line 101 at 706de1f0: Examples MUST also show what only the Enterprise Data File can do, because the examples are where a developer first sees what the paid data files add. (EX-7)
…with nothing set Answers pipeline-specification/required-examples.md line 30 at 706de1f0: Every reference implementation MUST provide one example for the Derived Property Element. (EX-19)
…nd an example of it that needs no key, data file or network The element is in the pipeline.translation package, beside the Translation Element, which uses the same YAML 1.2 library. Answers pipeline-specification/required-examples.md line 30 at 706de1f0: Every reference implementation MUST provide one example for the Derived Property Element. (EX-19)
…script from a file, and the pipeline built from a configuration file Answers pipeline-specification/required-examples.md line 37 at 706de1f0: The example MUST show all four of the following. The fourth is EX-22. (EX-21)
…beside it and builds the same pipeline from a configuration file Answers pipeline-specification/required-examples.md line 37 at 706de1f0: The example MUST show all four of the following. (EX-21)
…at is not available Answers pipeline-specification/required-examples.md line 50 at 706de1f0: This case MUST be shown rather than only described, because it is the behaviour customers most often meet first and the one the two valued model exists to make plain. (EX-22)
…idity, and the message naming the missing property Answers pipeline-specification/required-examples.md line 50 at 706de1f0: This case MUST be shown rather than only described, because it is the behaviour customers most often meet first and the one the two valued model exists to make plain. (EX-22)
…ss exceptions Answers device-detection-specification/required-examples.md line 150 at 706de1f0: Examples MUST also demonstrate or at least document commonly used, but non-default settings. (EX-8)
…remise and cloud Answers device-detection-specification/required-examples.md line 225 at 706de1f0: Examples MUST be provided that illustrate basic usage of the API for both Cloud and On-Prem, using fluent builder and options file configuration, when executed as a console (command line) application. (EX-9)
…premise engine Answers device-detection-specification/usage-examples.md line 16 at 706de1f0: In particular, a cloud Engine MUST be a drop-in replacement for an on-premise Engine for performing Device Detection and querying the results. (EX-13)
…gives a star sign for every date of birth Answers pipeline-specification/required-examples.md line 7 at 706de1f0: The examples that MUST be implemented in the core are all demonstrations of how to create Flow Elements. (EX-18)
…nd month alone, and finds a sign that runs over the end of the year Answers pipeline-specification/required-examples.md line 7 at 706de1f0: The examples that MUST be implemented in the core are all demonstrations of how to create Flow Elements. (EX-18) A date on the last day of a sign gave no sign, because each date kept the time of day it was made at, and Capricorn was never found, because its start is after its end.
…or, names the variable to set and links to the configurator, tagged with its own file Answers device-detection-specification/required-examples.md line 140 at dbaf099c: A cloud example run with no Resource Key MUST end without an error, name the environment variable to set, give a link to where a Resource Key is created, such as the configurator, and exit successfully, so that its test runs it with no arguments or settings. (EX-25)
…d with the example's file Answers device-detection-specification/required-examples.md line 140 at dbaf099c (EX-25). The first form of the test passed for four examples whose configurator link names the shared key helper, because their Find out more links carry the example's own tag.
…set and links to the configurator tagged with its own file, and ends without an error Answers device-detection-specification/required-examples.md line 140 at dbaf099c: A cloud example run with no Resource Key MUST end without an error, name the environment variable to set, give a link to where a Resource Key is created, such as the configurator, and exit successfully, so that its test runs it with no arguments or settings. (EX-25) The IP Intelligence cloud examples threw with no key. The Device Detection ones tagged the link with the shared key helper's file. The minimal example also takes its key from TestResourceKey and names it, and treats an empty key as none.
…ng for an update of the engine now Answers device-detection-specification/required-examples.md line 323 at 706de1f0: Implementors SHOULD illustrate: (file system watcher, remote update polling, update on start-up, programmatic (non-automatic) update). (EX-11)
…g the data update service for an update of the engine now Answers device-detection-specification/required-examples.md line 323 at 706de1f0: Implementors SHOULD illustrate: (file system watcher, remote update polling, update on start-up, programmatic (non-automatic) update). (EX-11)
…e Accept-CH header and by getHighEntropyValues in the client-side JavaScript Answers device-detection-specification/required-examples.md line 250 at 706de1f0: The example SHOULD illustrate various techniques for obtaining high entropy values for presentation to the origin server as well as to the 51degrees cloud service. (EX-10)
… by Accept-CH and by getHighEntropyValues, and that the cloud example presents them to the cloud service Answers device-detection-specification/required-examples.md line 250 at 706de1f0: The example SHOULD illustrate various techniques for obtaining high entropy values for presentation to the origin server as well as to the 51degrees cloud service. (EX-10) The options files' comment said getHighEntropyValues could not run in a secure origin. Browsers give the values only to a secure origin or localhost, and the comment now says so.
…ss, and by nothing else Answers pipeline-specification/usage-examples.md line 13 at 706de1f0: Creating Flow Elements SHOULD always be done using a consistent mechanism. (EX-24)
…n engine is only made by its builder Answers pipeline-specification/usage-examples.md line 13 at 706de1f0: Creating Flow Elements SHOULD always be done using a consistent mechanism. (EX-24) Every other Flow Element is made by its builder alone. TranslationEngineBase was a concrete class with no builder, which nothing made directly.
…aring Element, and says to add one in normal operation Answers device-detection-specification/required-examples.md lines 201 and 209 at dbaf099c: Reference implementations inhibit usage sharing for console examples by ensuring the Usage Sharing Element is not added to the Pipeline, but enable it for web examples. Every example in which usage sharing is inhibited needs to have a comment saying that in normal operation usage sharing should be enabled by adding a Usage Sharing Element to the Pipeline.
…ng off in its options file, with the comment saying to share usage in normal operation Answers device-detection-specification/required-examples.md lines 201 and 209 at dbaf099c: Reference implementations inhibit usage sharing for console examples by ensuring the Usage Sharing Element is not added to the Pipeline, but enable it for web examples. Every example in which usage sharing is inhibited needs to have a comment saying that in normal operation usage sharing should be enabled by adding a Usage Sharing Element to the Pipeline. The example built its Pipeline with the FiftyOnePipelineBuilder, which adds a Usage Sharing Element unless ShareUsage is false, so every run shared the example's evidence.
…t before its type parameter, so it is not read as part of it Follows the fix for pipeline-specification/usage-examples.md line 13 at 706de1f0 (EX-24).
rc moved the examples off the packages' test helpers in #175, so TacCloud and UpdateDataFile take the key helper from the examples' own shared module whilst keeping this draft's ending for an example run with no resource key.
… and build the example links so the link lint can read them
…ith no key to the drafts that carry them The Derived Property Element and its example are #156's, Comparer on the free data file is #158's, and every cloud example ending cleanly with no resource key is #163's, so each file this draft changed only for those is put back to rc's version. The cloud cases of the no-settings tests go with them, as #163's tests cover each cloud example run with no key.
…uration coverage test
TranslationEngineBase and its public constructor are in the last release, so code may make one with new. The only sentence behind making it abstract is a SHOULD, "Creating Flow Elements SHOULD always be done using a consistent mechanism", and a SHOULD leaves released behaviour as it is. TranslationEngineBasePublicTests holds the class concrete with a public constructor. ElementCreationConsistencyTest treats a class whose name ends in Base as a base class rather than a Flow Element, so a released base class that is still concrete is not required to have a builder.
TranslationEngineBase is concrete with a public constructor again, as in the last release, so code that makes one with new still compiles. Its documentation says to make a translation engine through its builder. Making the class abstract is a breaking change that no MUST requires, so it waits for a release that may break.
ben51degrees
marked this pull request as ready for review
November 19, 2026 05:08
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The specification this brings the code into conformance with
All quotations are at specifications dbaf099c.
mainstarts it.setSuppressProcessExceptions(true)". The on-premise web example's configuration file already set it, asSuppressProcessException, and nothing held it there.What changed
Links are to the head, f34859be.
ShareUsageExamplesends to an endpoint it is given, andShareUsageExampleTestgives it one in the test, so the test shares nothing with the live service.gettingStartedOnPrem.xml, with the comment the specification asks for, andGettingStartedOnPremUsageSharingTestholds both.mainstarts it, through astart(port)methodmainnow calls, andWebOnPremWithoutSettingsTestholds that.NonDefaultSettingsTestholds its configuration file to settingSuppressProcessExceptionwith a comment saying why, which it already did. The comment in51Degrees-OnPrem.xmlon secure origins now says that browsers rungetHighEntropyValuesonly in an https origin or on localhost.ConsoleConfigurationCoverageTestholds the console examples to showing both the fluent builder and an options file, for on-premise and cloud.Accept-CHheader and bygetHighEntropyValuesin the client-side JavaScript, and that the cloud example presents them to the cloud service.HighEntropyValuesTestin each web example holds the page to it.UpdateDataFileshows a programmatic update through the data update service, andProgrammaticUpdateTestholds it.CloudDropInTestreads the results of the cloud engine and the on-premise engine through the same code.ElementCreationConsistencyTestholds every Flow Element in the repository to being made by its builder class.TranslationEngineBasestays concrete with its public constructor, as released, because only a SHOULD asks for one way of making Flow Elements, and its documentation says to make a translation engine through its builder. The test treats a class whose name ends inBaseas a base class, andTranslationEngineBasePublicTestsholds the released class concrete (7014ac9, f34859b).ExampleTestsbuilds it, runs it in a Pipeline and checks a sign for every date of birth.Before you upgrade
No public class or method changes.
TranslationEngineBasestays concrete, as released.What this draft no longer carries
At bd93f86c this draft put back
rc's version of every file it changed only for work that three other drafts carry, so each piece of work is in one draft.WithoutKeyTestfiles went with it, as End every cloud example cleanly when it has no resource key #163's tests run each cloud example with no key. The usage sharing example's case in the no-settings test went too, because run with no settings it sends to the live service.Tests
Red, run 43913952515 on
tmp/red-173b, one job per test commit, each building its module and running the new test in that module alone. All five failed.ElementCreationConsistencyTestfails, "TranslationEngineBase is made by no builder". The test now treats a class named...Baseas a base class (7014ac9), so it fails for any other concrete Flow Element made outside a builderGettingStartedOnPremUsageSharingTestfails 2 of 2, "The example's Pipeline should not share usage" and the options file comment missingExampleTestsfails 2 of 4, "expected: but was: " for the first and last days of a sign and "expected: but was: " across the end of the yearHighEntropyValuesTestfails 2 of 2, the page not naminggetHighEntropyValuesand the options file comment saying it fails in a secure originstart(int), which only the fix adds. So this job shows the test cannot pass without the fix, not a test failing at run timeTwo more test commits stop at test compile for the same reason, and an earlier run shows it, 43870415154:
ProgrammaticUpdateTest(a816cd7) callsupdateNow, andShareUsageExampleTest(b627d35) the endpoint the fix adds. That earlier run's other three jobs stopped before their test ran, because its test step ran on every module, so they are not cited.ConsoleConfigurationCoverageTest,CloudDropInTestandNonDefaultSettingsTestcover what the examples already did and have no red. A full build of bd93f86, run 43910501413, failedConsoleConfigurationCoverageTest.onPremiseOptionsFilein four of its nine jobs with "[IPIntelligenceOnPremiseEngine]", because the test foundgettingStartedOnPrem.xmlby searching the file system and, from where those jobs ran, found the IP Intelligence example's file of the same name first. Commit 06ac80d reads each options file from the Device Detection example's own resources.Red and green of the
TranslationEngineBasefix, run 44451557389 ontmp/fixconf-java-173(workflow commit f7ef66e on f34859b). The red job ranTranslationEngineBasePublicTestsat the test commit 7014ac9 and failed as intended,translationEngineBase_IsConcrete"TranslationEngineBase is abstract, so code that makes one with new no longer compiles". The green job ran every test ofpipeline.core,pipeline.translationandip-intelligence.translation, the module whose engines extendTranslationEngineBase, at f34859b, and all passed, 160, 55 and 23 tests with 1 skipped,ElementCreationConsistencyTestandTranslationEngineBasePublicTestsamong them. The run reports failure only because the red job failed, as it should.Green, the full build below, of 06ac80d, and the green job above for the two commits after it.
Build
Run 43940789635 built 06ac80d merged with
rcon 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. Configure and all nine Build and Test jobs passed, read from each job's log, andConsoleConfigurationCoverageTestpassed 2 of 2 in all nine. Each of its tenSetting 'PullRequestSha'lines names 06ac80d, and its Configure job printed "Left out 6 macOS entries". The run's last job, which only gathers the results, was still running when the build was first written up.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
rc81e3d4a is merged into the head with a merge commit, and the head merges into today'srcwith no conflict. The examples'KeyHelperchanges this draft made for the no-key endings went with them at bd93f86.Changes at the last head
7014ac9 adds
TranslationEngineBasePublicTests, and f34859b makesTranslationEngineBaseconcrete again with its public constructor, as released, so nothing about it is listed under Before you upgrade. The title no longer names Comparer, which another pull request carries, and What remains names the one example still without a no-settings run.What remains
ShareUsageExampleTestruns it against an endpoint it gives. A no-settings run that checks only that it starts and stops, with the endpoint unreachable, would close that.WebOnPremWithoutSettingsTestleavesTestDataFileset to the Lite file when it was not set before, because the example sets it while finding its data file. Clearing it in the test'sfinallywould keep it from reaching a later test in the same JVM.TranslationEngineBaseabstract, so a translation engine is made only by its builder, waits for a release that may break public names.