On 11 May 1985, Richard Stallman sat at a computer at MIT and wrote down what he had changed that day in GNU Emacs, a text editor. He had made sure one part of the program behaved on certain terminals. He had stopped people from doing something confusing in another part. The next day he added a note that sounded almost proud: one tidy-up had saved 2,500 bytes.[1]
Those notes still exist. They sit at the bottom of a file of old change notes that is still kept with Emacs today. Over the same few days, other names appear above his, each entry signed and dated.[1] Nobody outside a small circle would ever read them.
A diary for the next person
By 1992, the GNU project had turned the habit into a rule. Its coding standards told programmers to keep a change log for each folder of code and explained why: so that whoever came hunting for a bug later could see what had recently changed.[2]
The standards were oddly philosophical about it. A change log, they said, could explain how two clashing ideas had ended up in the same program. They described it as a kind of undo list. People can already see the current version, the reasoning went, so what they need is a clear account of how the old one was different.[2]
There were firm opinions about what did not deserve a log. Fixing a comment needed only a two-word note. Manuals needed no log at all, because, the standards argued, documentation does not break in the complicated ways code does.[2]
So the first changelogs were written by programmers, for programmers, and mostly for their future selves. Customers were not invited.
Read this first
Customers got something else: the README, a plain text file that came with the disks and held whatever had not made it into the printed manual.
Microsoft's README for MS-DOS 6.22 opened by saying so. It held important information that was not in the user's guide or the help screens. It ran to about 1,400 lines, with advice such as what to do if you had deleted files that setup still needed: put Setup Disk 1 back in the drive and start again.[3]
The README was a confession that the manual had already gone out of date by the time it was printed. Then the README needed corrections of its own. Microsoft later published a list of mistakes in its MS-DOS 6.22 documentation, including a handful in the README, such as one section pointing readers to the wrong section.[4]
Updates in everyone's pocket
For most people, release notes stayed invisible until the phone. Apple's App Store opened in July 2008, and within days people had downloaded more than 10 million apps from a catalogue of more than 800.[5] Every app could now be updated whenever its maker liked, and every update came with a short box explaining what was new.
Suddenly ordinary people were reading changelogs, or at least scrolling past them. And app makers started to find the box a chore.
By September 2015, TechCrunch's Sarah Perez had had enough. She wrote that app makers were getting careless with their release notes, and listed Yahoo, Hulu, Google, Flipboard, LinkedIn and Microsoft among those leaning on vague lines such as "Bug fixes and performance improvements."[6]
Facebook had gone further. Its notes simply said the app was updated every two weeks, that every update made it faster and more reliable, and that any new features would be pointed out inside the app.[6]
The two sides of the argument were both reasonable. A Facebook engineer explained that most changes were tiny or invisible, and that new features reached people a few at a time, so naming one could confuse everyone who did not have it yet. Perez's answer was that people deserved to know whether an update was a small fix, a security patch, or a change to how the company made money.[6]
Jokes, stories and a T-shirt
Other companies decided that if nobody read the box, they might as well make it worth reading.
In the summer of 2015, Medium replaced its notes with a transcript of its own developers chatting about the release. Then it ran a contest instead: spot the one important change hidden among the bug fixes and win a T-shirt.[7] Another time, its notes were a pretend phone call with Grandma. One update said nothing but the word "FIXES" under a little drawing of a bug.[6]
Tinder's notes promised the update was "Jam packed full of Super Amazing Things," which TechCrunch singled out as one of the worst offenders.[6]
Then, in August 2015, Tumblr published notes for version 4.3.1 of its iPhone app in the form of a short story starring its chief executive, David Karp. It began: "'4.3?' roared David Karp across the boardroom table."[8] The joke was that there had never been a version 4.3. Readers loved it. TechCrunch pointed out that the story forgot to say what had actually changed.[6]
Slack was the company that people held up as doing it properly. Its notes were funny, but they also said what was fixed, which TechCrunch noted with approval.[6] A 2024 look back at Slack's notes explains where the voice came from. Slack began life as a video game called Glitch, and the team wanted its work tool to be pleasant to spend time in.[9]
Anna Pickard at Slack wanted the notes to prove that the app kept getting better and that someone was reading the bug reports. They were also meant to point out small features people would never find on their own, give the engineers credit, admit past mistakes, and be fun enough that people would read them and pass them on.[9] The stock line about minor improvements and bug fixes was ruled out as not their style. One note from October 2015 promised that links meant to open in Chrome would now open in, as the note put it, all together now, Chrome.[9]
For humans, not machines
Back among programmers, the old diary had a problem. Tools now recorded every small change automatically, and many projects simply pasted that raw record in and called it a changelog.
In 2014, a developer named Olivier Lacan put up a small website called Keep a Changelog. Its slogan asked people not to let their friends do exactly that. Lacan's point was that a raw list of every change is full of noise, and that the people using software care only about the changes that matter to them.[10]
His guiding principle was short: "Changelogs are for humans, not machines."[10] He was blunt about the older GNU guidance, calling it inadequate, and he suggested a plain name for the file, CHANGELOG, while admitting that some projects call it HISTORY, NEWS or RELEASES.[10]
The guide to keeping a changelog keeps one of its own. The first entry is dated 31 May 2014.[11]
The changelog as a shop window
By then, the changelog had quietly moved from the back of the box to the front of the shop.
In May 2020, Karri Saarinen of the software company Linear wrote an essay telling startups to keep public changelogs. Linear had started one while it was still building its product and had kept it going for a year.[12]
He argued it kept the team moving, made early users feel heard, and drew in new customers and job candidates. He also mentioned who else was reading. Most of the angel investors and venture capitalists he met, he wrote, said they had been following Linear's changelog.[12]
These were people who did not necessarily use the product. They were reading the list of what had changed the way others read a newspaper, to see who was moving and who was not.
Saarinen's advice was to publish on a schedule, every week or two, and not let it slip. And if a week came with nothing to write, he said, the thing to look at was why the work had slowed down.[12]