:INFO [align:center]
whence
It parses the dates people actually type. "next tuesday". "in 3 weeks". "end of the month". "18/03" with no year, from a user whose locale you are only guessing at. Seven years of getting that wrong in public, written down in order, because the interesting part of a date library is never the parsing. It is the corrections.

|
:INFO
Why This Page Is A Timeline
Most of what you need to know about a date library is historical. Which version silently changed how it resolves an ambiguous day. Which one broke across a DST boundary and only in the southern hemisphere. Which one you are pinned to and why somebody on your team wrote "do not upgrade" next to it in 2023. Feature lists cannot tell you that. A list of dated mistakes can.

|
:TIMELINE
The first three years
2019-04-01 | v0.1.0. Parsed six English phrases. Written for one internal form. Published mostly by accident.
2019-11-01 | v0.6.0. First bug report from a stranger. "next friday" on a Friday returned today. It still divides people.
2020-02-01 | v0.9.0. Locale support added badly. Day-first and month-first were decided by a regex on the string.
2020-07-01 | v1.0.0. That regex was removed. Locale became a required argument. First breaking change and the right one.
2021-03-01 | v1.4.0. "end of the month" landed on the 30th in February. Live for 11 days. Nobody noticed until March.
2021-10-01 | v1.6.0. Timezone handling moved off the host clock. Three years of latent bugs closed in one release.
|
:INFO
The Two That Actually Cost Something
Everything above was embarrassing. The two entries below were worse than that, because they reached people who were not developers and had no idea a library was involved. Both are described here at more length than is comfortable. A changelog that quietly drops its worst day is a changelog that has learned nothing and is teaching nobody.

|
:TIMELINE
The two that cost something
2022-03-27 | v2.1.0. DST. "tomorrow at 9" resolved to 08:00 across a spring-forward boundary in Europe.
2022-03-27 | Live for 5 days. A booking product shipped it on the Friday. Monday was a lot of missed appointments.
2022-04-01 | v2.1.1. Fixed by holding wall-clock intent and resolving the zone last. The rule the library should always have had.
2023-09-14 | v2.6.0. Southern hemisphere DST inverted. Same class of bug, opposite sign, missed by every test we had.
2023-09-16 | Found by a user in Auckland who wrote the clearest bug report this project has ever received.
2023-09-17 | v2.6.1. Test suite now runs in 14 timezones on every commit. That is the actual fix.
|
:STATS
|
:QUOTE [quotetype:plain, subtitle:from the Auckland bug report on issue 402]
Your tests pass because they all run north of the equator. Mine is the half of the world where the clock goes the other way.

|
:TIMELINE
Since then
2024-01-01 | v3.0.0. Breaking. Ambiguous input now returns a range rather than a guess. The most requested and most argued change.
2024-08-01 | v3.2.0. "in 3 weeks" now respects the caller's week start. Reported by a Danish team in 2020.
2025-05-01 | v3.5.0. Nothing broke. 14 months without a behaviour regression is the current record.
2026-02-01 | v3.7.0. Deprecated the last function that reads the host clock implicitly. Removal scheduled for v4.
|
:INFO
What Changed In How We Work
None of the fixes above were the real fix. The real fixes were structural and there are three: locale is a required argument rather than a guess, the test suite runs in fourteen timezones on every commit rather than in the maintainer's own, and ambiguous input returns a range instead of a confident wrong answer. Every one of those was forced by a bug that had already shipped.

|
:CHECKLIST
If you are upgrading
[ ] Read the entry for every version between yours and the target. All of them
[ ] Pin exactly. Caret ranges on a date library are how the 2022 DST bug spread
[ ] If you are on v2, the v3 range return is the only breaking change that matters
[ ] Run your own suite in at least two timezones before you believe any of this
[ ] If you find something, the Auckland report is the template. It is linked below
|
:LINK
https://github.com/whence-dev/whence/issues/402
Issue 402, the best bug report this project has had
|
:LINK
https://www.npmjs.com/package/whence
whence on npm