[jwrosewell]

What was wrong

rc renamed environment variables and stopped reading the old names, in what is a patch release. #105, "Give every environment variable one 51DEGREES name", renamed the cloud endpoint variable from FOD_CLOUD_API_URL to _51DEGREES_CLOUD_ENDPOINT and gave the data file and key variables names that start with an underscore. Every file in the first table below is among the files that pull request changed. A deployment, a developer or a build that sets an old name would, after upgrading, be ignored with no error and no message. For the endpoint that means requests meant for a private host go to cloud.51degrees.com.

Six public constants that held an old name were also renamed or given a new value, so code that names Constants.FOD_CLOUD_API_URL no longer compiles, and code that passes one of the other five to the environment reads a different variable.

#105 was opened and merged into rc by jwrosewell at 19:36 UTC on 11 November 2026, with no review recorded on the pull request. Nothing has been released with the renames, because main at f69da52 still holds the old names. The release draft #112 waits for this change.

The rules this follows

James Rosewell, at about 11:40 UTC on 12 November 2026:

A patch release never removes or renames a public name. The old name stays for at least one release, deprecated and pointing at the new one.

Asked at about 12:05 UTC whether that covers an environment variable name a package reads as well as names in code, he answered:

Yes, env names too

Asked at about 16:55 UTC whether it covers environment variable names that tests and examples read as well as packages, he answered:

How could they not be if they're needed for tests?

And examples? Some people will want to run the tests themselves. That's a good thing.

They were always public!!

So every environment variable name that a package, a test, an example or a CI script in this repository reads is a public name. Where a name changed, the old name is read when the new one is not set or is empty, with a message that the old name is deprecated and which name replaces it. A package logs the message once through its own logger, and a test helper or an example prints or logs it once. This draft began with the cloud endpoint alone and was widened to every name after the third answer, in the same draft.

No specification names these variables. A code search of the default branch of the specifications repository on 12 November 2026 finds neither FOD_CLOUD_API_URL nor _51DEGREES_CLOUD_ENDPOINT.

Every name that changed, and where it is read

The list comes from every file of main at f69da52 and of rc at 0b9257f, searched for each old and new name and for every System.getenv call. The last release of every package, 4.5.130 of 5 November 2026, is tagged at that same main commit. Each row is one reader. The last column is at the head, 02b1bca.

Old name	New name	Reader	main read the old name	rc read only the new name	Head reads the new name, then the old
FOD_CLOUD_API_URL	_51DEGREES_CLOUD_ENDPOINT	Cloud request engine builder (package)	lines 86 to 93	lines 97 to 106	endPointFromEnvironment, lines 165 to 190
FOD_CLOUD_API_URL	_51DEGREES_CLOUD_ENDPOINT	51Did client (package)	line 1116	line 1162	resolveEndpoint, lines 1174 to 1206
FOD_CLOUD_API_URL	_51DEGREES_CLOUD_ENDPOINT	Cloud engine example	line 62	line 69	endpoint, lines 92 to 119
RESOURCE_KEY	_51DEGREES_RESOURCE_KEY	Cloud engine example	lines 77 to 81	lines 92 to 97	configuredResourceKey, lines 141 to 162
RESOURCE_KEY, LICENSE_KEY	_51DEGREES_RESOURCE_KEY, _51DEGREES_LICENSE_KEY	51Did example	lines 121 to 124	lines 121 to 124	key, lines 472 to 486
RESOURCE_KEY, LICENSE_KEY	_51DEGREES_RESOURCE_KEY, _51DEGREES_LICENSE_KEY	51Did live tests	lines 62 to 66	lines 69 to 75	LiveCloudKeys.find, lines 90 to 112
51DEGREES_IPI_PATH	_51DEGREES_IPI_PATH	IP Intelligence test helper FileUtils	lines 107 to 111	lines 107 to 111	getExplicitHashFile, lines 123 to 144
51DEGREES_IPI_PATH	_51DEGREES_IPI_PATH	IP Intelligence example helper DataFileHelper	lines 218 to 221	lines 407 to 410	getDataFileLocation, lines 431 to 458
51DEGREES_IPI_PATH	_51DEGREES_IPI_PATH	Country translation integration test	line 69	line 69	pathFromEnvironment, lines 77 to 93
51DEGREES_RESOURCE_KEY	_51DEGREES_RESOURCE_KEY	IP Intelligence test helper KeyUtils	lines 47 to 53	lines 47 to 53	getResourceKey, lines 63 to 83
51DEGREES_RESOURCE_KEY	_51DEGREES_RESOURCE_KEY	IP Intelligence example helper KeyHelper	lines 71 to 80	lines 156 to 165	requireResourceKey, oldNameResourceKey and getOrSetResourceKey, lines 84 to 209
51DEGREES_DD_PATH	_51DEGREES_DD_PATH	On-premise web example of Device Detection	line 35	line 35	line 36, with a warning from warnOfOldDataFileName, lines 73 to 82

Names that did not change between main and rc need nothing, being TestResourceKey, SuperResourceKey, TestDataFile, LicenseKey, TestCloudEndPoint and the _51DEGREES_RESOURCE_KEY_BESPOKE, _51DEGREES_RESOURCE_KEY_51DID and _51DEGREES_LICENSE_KEY_51DID names the workflows set. No CI script on main read or set an old name.

Three of the old names start with a digit. On main each of their readers took the name as an environment variable and then as a Java system property, and the fallback keeps both. On the Ubuntu runner only the system property reached the tests. Run 43287526584 set two of those names in the environment of the step that runs Maven, and the two tests that fail when the names are read passed. Run 43289150046 gave the same two names as system properties and those tests failed. That second run also printed what a child process saw of the names in the environment, which was both names for a child of bash and neither for a child of sh.

The constants that held an old name:

Constant	main	rc	Head	Holds the new name
Constants.FOD_CLOUD_API_URL (cloud request engine, package)	"FOD_CLOUD_API_URL"	gone, renamed CLOUD_ENDPOINT_VARIABLE	back, "FOD_CLOUD_API_URL", @Deprecated	Constants.CLOUD_ENDPOINT_VARIABLE
DidClient.ENDPOINT_VARIABLE (51Did, package)	"FOD_CLOUD_API_URL"	"_51DEGREES_CLOUD_ENDPOINT"	"FOD_CLOUD_API_URL", @Deprecated	DidClient.CLOUD_ENDPOINT_VARIABLE, new
FileUtils.IPI_PATH_ENV_VAR (IP Intelligence test helpers, package)	"51DEGREES_IPI_PATH"	"_51DEGREES_IPI_PATH"	"51DEGREES_IPI_PATH", @Deprecated	FileUtils.IPI_PATH_VARIABLE, new
KeyUtils.RESOURCE_KEY_ENV_VAR (IP Intelligence test helpers, package)	"51DEGREES_RESOURCE_KEY"	"_51DEGREES_RESOURCE_KEY"	"51DEGREES_RESOURCE_KEY", @Deprecated	KeyUtils.RESOURCE_KEY_VARIABLE, new
DataFileHelper.IPI_PATH_ENV_VAR (IP Intelligence examples)	"51DEGREES_IPI_PATH"	"_51DEGREES_IPI_PATH"	"51DEGREES_IPI_PATH", @Deprecated	DataFileHelper.IPI_PATH_VARIABLE, new
KeyHelper.RESOURCE_KEY_ENV_VAR (IP Intelligence examples)	"51DEGREES_RESOURCE_KEY"	"_51DEGREES_RESOURCE_KEY"	"51DEGREES_RESOURCE_KEY", @Deprecated	KeyHelper.RESOURCE_KEY_VARIABLE, new

What changed

1. Each reader in the first table reads the new name first and the old name only when the new one is not set or is empty. When both are set the new name wins and nothing is said.
2. Each says once that the old name is deprecated. The two packages log a warning once in a process (the cloud request engine through the builder's logger factory, and the 51Did client through java.util.logging, because that module depends only on org.json and its build file says it adds no dependency the pipeline does not carry). The examples log a warning through the SLF4J logger they already hold, except the 51Did example, which has no logger and prints to standard error, as the test helpers do. Every message has the same form, for example "The environment variable FOD_CLOUD_API_URL is deprecated and _51DEGREES_CLOUD_ENDPOINT replaces it. Set _51DEGREES_CLOUD_ENDPOINT to the same value, as a later release may no longer read FOD_CLOUD_API_URL."
3. Each constant in the second table holds its old value again and is marked @Deprecated, with a @deprecated note pointing at the constant that holds the new name. Code in this repository that named one of the old constants to tell a reader which variable to set now names the new constant, so every message and document still gives the _51DEGREES_ name.
4. The on-premise web example takes its data file from a configuration file, so the old name is read by one more level in the DataFile setting, and the warning comes from the example's main.
5. The name check allows an old name only where it is read as a deprecated fallback. ci/check-environment-variable-names.ps1 keeps FOD_CLOUD_API_URL, RESOURCE_KEY and LICENSE_KEY in its pattern and still fails on any name that starts with a digit. DeprecatedFallbacks, lines 77 to 117 lists the 22 files that read an old name or test that read, each with the old names it may hold, and Test-DeprecatedFallback, lines 123 to 130 lets a match through only for a listed file and a name listed for it, in its exact case. Everywhere else the check fails as before.
6. One paragraph in pipeline/README.md, line 142 says the old endpoint name is deprecated and still read.
7. Nothing else about the endpoint or the keys changes. A value given in code still wins over both names, the defaults are the same, and each reader keeps its own test for "not set". The one difference is in the two IP Intelligence data file helpers, where an empty value now counts as not set. Before, an environment variable set to the empty string hid the system property of the same name, and now the system property is read.

One name is left as rc has it. The 51Did workflow on main passed the organisation variable _51DEGREES_RESOURCE_KEY_BASIC to its tests, and #59 took it out, saying the workflow "drops the basic key, which does not carry the fodid product: the tests now insist on a 51Did, so that key would report a failure that is entitlement working correctly". That is a key the workflow no longer runs with and not a name that changed, and putting it back would turn the check red, so this draft does not touch it.

Tests

The tests went in first each time. Commit 2e7bdc6e is the endpoint tests alone and 98996a06 the endpoint fix. Commit a5b1ee6f is the tests for every other name alone and 3b2bef1d the fix for them. Commit 02b1bca0 changes two existing tests that review found failing wherever an old name is set, and nothing else.

Tests	What they check
CloudRequestEngineBuilderTests, lines 194 to 268, six new	Only the old endpoint name gives that endpoint. An empty new name with the old one set gives the old one's endpoint. Both set gives the new name's endpoint and logs nothing. An endpoint set in code beats the old name. Two engines built from the old name log one warning between them. Constants.FOD_CLOUD_API_URL holds "FOD_CLOUD_API_URL" and carries @Deprecated. The existing CloudEndPoint_Default_Setting covers neither name set
DidClientEnvironmentTests, six new, with EndpointProbe	The client reads System.getenv directly and a Java process cannot change its own environment, so each test starts a second Java process with the variables it needs. Only the old name gives its endpoint, and logs one warning for two clients. A blank new name gives the old name's endpoint. Both set gives the new name's. Neither gives the default. DidClient.ENDPOINT_VARIABLE holds "FOD_CLOUD_API_URL" and carries @Deprecated
LiveCloudKeysTests, four new	RESOURCE_KEY and LICENSE_KEY are each read when their new name is not set, the new name wins, and an old name is read only in place of its own new name
EndpointTests of the cloud engine example, five new	Only the old endpoint name, both, and neither. Only RESOURCE_KEY, and both key names
DeprecatedKeyNameTests of the 51Did example, four new, with KeyProbe	The example reads its keys once when its class loads, so each test starts a second Java process. The old names alone give their keys and each is reported once. Both names give the new ones and report nothing. No names give no keys
FileUtilsTest and KeyUtilsTest, three new each	Only the old name is read, the new name wins, and the old constant keeps its value, carries @Deprecated and has a new constant beside it
DataFileHelperTest and KeyHelperTest, three new each	The same three for the example helpers
OnPremDataFileOptionTest, two new	The configuration takes the data file from 51DEGREES_DD_PATH ahead of TestDataFile, and from _51DEGREES_DD_PATH ahead of both
check-environment-variable-names.Tests.ps1, lines 93 to 150, 15 new cases	The check passes a repository whose DidClient.java holds the old endpoint name and fails one that holds it in any other file. Test-DeprecatedFallback allows five name and file pairs and refuses eight, among them a listed file with a name it is not listed for and a name in the wrong case
KeyHelperTest.getOrSetTestResourceKey_NoKey_StoresNothing, lines 52 to 85 and ExamplesWithoutSettingsTest.runWithoutSettings, lines 57 to 96, existing tests	Each runs a helper with nothing set, and checked and cleared only the new name. The helpers now read the old name too, so each test also skips when the old name is in the environment and clears it as a system property

The country translation integration test has no test of its own for the old name, because it reads the environment directly, needs a data file and is skipped without one.

Runs

Run	Built	Result
Red, full build, 43245288801	Endpoint tests alone, 2e7bdc6	Failed, as it should. Ubuntu_Java_8 failed in the 51Did module with 4 of the 6 new tests failing, for example oldNameAlone_GivesItsEndpoint with "expected:<[https://old.example/api/v4/, ...]> but was:<[https://cloud.51degrees.com/api/v4/, ...]>". The other eight configurations were cancelled when that one failed, and Maven stopped at that module
Red, the three endpoint test classes, 43249805806	2e7bdc6 and a temporary workflow, 1e7e0312	Failed, as it should, on Ubuntu and Windows with Java 8 and 21. Builder 4 of 10 failed, 51Did 4 of 6, example 1 of 3
Green, the same three classes, 43249923106	98996a0 and the same workflow, 91e409a6	Passed on all four, none skipped
Green, full build of the endpoint fix, 43251146916	98996a0	Passed on nine configurations. This head has since moved
Red, name check, 43245251344 and 43269407170	2e7bdc6 and a5b1ee6	Failed, as they should, with 6 and then 18 Pester cases failing
Red, the ten test classes this draft touches, 43269425046	The tests for every other name alone, a5b1ee6, and a temporary workflow, 71f84bda	Failed, as it should, on Ubuntu with Java 8 and 17. Eight of the ten classes failed, each on its old name tests, for example KeyUtilsTest.oldKeyNameIsReadWhenNewIsNotSet with "expected: but was:" and OnPremDataFileOptionTest.usesOldDdPathWhenNewIsNotSet with "expected:<from-[old-dd-path].hash> but was:<from-[test-data-file].hash>". The two that passed are the endpoint classes, which 98996a0 had already fixed
Green, the same ten classes, 43269595952	3b2bef1 and the same workflow, dd3b2c65	Passed on both. Ten classes and 54 tests ran, none failed, none skipped
Green, full build of the fix for every other name, 43271325883	3b2bef1	Passed on nine configurations. This head has since moved
Red, the two guarded tests with the old names set, 43289150046	3b2bef1 and a temporary workflow, 7f6756f6	Failed, as it should, on Ubuntu with Java 8 and 17. The two test classes ran with 51DEGREES_RESOURCE_KEY set to a value shaped like a key and 51DEGREES_IPI_PATH set to the root pom.xml, both as system properties. getOrSetTestResourceKey_NoKey_StoresNothing failed with "expected null, but was:", and 8 of the 9 ExamplesWithoutSettingsTest tests ended in an error at runWithoutSettings, because the examples took the pom as their data file
Green, the same two classes with the same settings, 43289167800	The head and the same workflow, 0f6691a2	Passed on both. 7 and 9 tests ran, none failed, none skipped
Green, full build, 43290953104	The head, 02b1bca	Passed. It started at 19:31 UTC and finished at 20:56 UTC on 12 November 2026, on nine configurations (Ubuntu with Java 8, 11, 17 and 21, Ubuntu ARM with Java 17, and Windows with Java 8, 11, 17 and 21). The Setting 'PullRequestSha' line in Configure and in each of the nine build jobs is 02b1bca, and Configure printed "Left out 6 macOS entries". In each of the nine, the eleven JUnit test classes listed under Tests ran their 63 tests with none failed and none skipped
Quick checks on the head	02b1bca	Name check, link lint and only rc into main all passed

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.

What remains

1. The old names stay for at least one release. Taking them out later means deleting the six deprecated constants and the reads in the first table, and emptying DeprecatedFallbacks in ci/check-environment-variable-names.ps1.
2. #112 says under "Before you upgrade", item 9, that "The old name is no longer read" and that Constants.FOD_CLOUD_API_URL "is now" Constants.CLOUD_ENDPOINT_VARIABLE, and its "Environment variables" section says the examples, tests and CI scripts "read only the new names". Once this merges, both need to say that every old name is deprecated and still read.
3. The temporary branches tmp/endpoint-java-red, tmp/endpoint-java-green, tmp/endpoint-java-red2, tmp/endpoint-java-green2, tmp/endpoint-java-red4 and tmp/endpoint-java-green4 are kept so the commits linked above stay reachable. They can be deleted once this is merged.
4. James Rosewell asked at about 17:20 UTC on 12 November 2026 for one list of the environment variable names every language reads, kept in common-ci, saying "We should add to common-ci the env vars that are being used across the languages and reference this from other places. This ensure consistency." A code search of common-ci on 12 November finds no such list yet. When it exists, DeprecatedFallbacks in the name check and the README paragraph should refer to it.
5. A question for the coordinator, which does not hold this draft. Does "never removes" reach a workflow that stops running with one of the organisation's keys, as the 51Did workflow did with the basic key? This draft reads it as no, for the reason given under "What changed".