customZone requirement to sort exceptions from latest to earliest?

[piratejon]

I thought the documentation for customZone (

time/src/Time.elm

Lines 550 to 557 in 7b97ef5

	2. A list of exceptions containing their `start` time in "minutes since the Unix
	epoch" and their `offset` in "minutes from UTC"
	Human times will be based on the nearest `start`, falling back on the default
	offset if the time is older than all of the exceptions.
	When paired with `getZoneName`, this allows you to load the real IANA time zone
	database however you want: HTTP, cache, hardcode, etc.

) is pretty straightforward but I couldn't get my timestamps to respect the custom zone definition. Finally I looked at the source and noticed it seems to rely on the exceptions being sorted from latest to earliest:

time/src/Time.elm

Lines 328 to 332 in dc3b75b

	era :: olderEras ->
	if era.start < posixMinutes then
	posixMinutes + era.offset
	else
	toAdjustedMinutesHelp defaultOffset posixMinutes olderEras

. In light of that, I now read "Human times will be based on the nearest start, falling back on the default offset if the time is older than all of the exceptions." as not just descriptive, but a consequence of a non-obvious implementation detail which imposes an unstated requirement on the input. I think it would be clearer if

time/src/Time.elm

Lines 550 to 551 in 7b97ef5

	2. A list of exceptions containing their `start` time in "minutes since the Unix
	epoch" and their `offset` in "minutes from UTC"

stated that the list of exceptions must to be sorted from latest to earliest.

[mingan]

Definitely tripped us up. It appeared when we had a series of values (for a chart) which fell into (a) DST -> (b) not DST -> (c) DST. We had values in (a) and (b) displayed correctly but values in (c) were shifted one hour back. After flipping the list of exceptions, the values appear correct.