There’s a clip that goes viral over and over of a man standing in the jungle. Out of the bushes a silverback gorilla charges, the man stands unintimidated and the gorilla turns back.

Takes a lot of guts to do that.1 A lot of guts to film, too! So I guess it’s not too surprising that the man2 who survived filming the charging gorilla met his end while attempting to film the rainforest canopy from this beautiful single-seat blimp.

And having witnessed this death, the man who built that blimp was racked with guilt and hoped to set things right by building another blimp so that he could film the rainforest canopy himself. The builder of both blimps was Graham Dorrington3, his documentarian became Werner Herzog, and I have not been able to figure out who funded the whole thing but whoever it was they did not have enough money to do it safely but exactly enough money to do it interestingly.

The White Diamond is free on YouTube, and makes a great meditative watch with young kids on a sick or rainy day.

Cooking mice

Mouse Hunt (1997) is an absolutely incredible kids movie, something like Home Alone but with the child-as-adult fantasy replaced with practical adult fears. It’s great fun, and somehow it ends like this:

Nathan Lane, the professional chef, with an anatomically conventional mouse on his shoulder taste-testing for him. I saw this movie in theaters once as a child, then again a few months ago, and I couldn’t believe that I had forgotten this scene. Because of course 10 years later this short closing scene would be expanded into the full-length Ratatouille.

What’s weird about it is that neither I, nor ChatGPT, Gemini, or Claude, can find any explicit link between these two movies. But it seems impossible to me that Ratatouille could exist if Mouse Hunt had not ended in the bizarre way that it did. Right? Though I suppose dirty mice and clean cooking are an obvious juxtaposition, maybe it’s coincidence…

Epic penguins

Another great Herzog movie which children can sort of tolerate is Encounters at The End Of World. The most famous bit, which seems to go viral every now and then, is this lone penguin who determinedly marches the wrong way, away from his colony, away from the ocean, towards the certain doom of the interior mountains on his own.

You can watch the penguin part here, or read the transcript in this footnote.4 The other day, January 23 2026, the Trump White House tweeted this:

Herzog is obsessed with insanity, which he refers to (in the penguin clip and elsewhere) as “derangement”. As with Mouse Hunt and Ratatouille, I suppose it’s possible this image of Trump is just a convergent riff on the paradox between the grandeur of mountains and the comedy of penguins. But it seems much more likely that the staffer who made this has seen the movie, or at least the penguin clip. The combination of Trump’s Greenland adventures and the “derangement” token pulled it into their context, and we get this astonishing little artifact to psychoanalyze.

EDIT: it seems the official accounts of Health Secretary Robert Kennedy and Homeland Security and various other right-wing accounts have also posted penguin memes which make it clear that everyone involved has seen the Herzog clip.

EDIT 2: excellent counterpoint tweet

Epilogue

The Gray Area with Sean Illing interviewed Werner Herzog in 2024. Here’s the transcript starting from 52:33

[Sean] You ask people at the end of Lo and Behold, if they thought the Internet dreams of itself… [Do you] think the Internet dreams of itself?

[Herzog] Well, that’s the deepest of all questions, I think, and not really fully answerable. I have to admit it is just a projection of a statement by a war theoretician, Napoleonic time, a Prussian war theoretician, von Klausewitz.

And apparently von Klausewitz once in his study on war, which is still a revolutionary insight into war, into warfare, he said it seems that war sometimes dreams of itself. It’s a stunning statement. And I extended it does the Internet dream of itself. The strange thing now is that experts on von Klausewitz told me von Klausewitz never said that. Maybe I invented it and talked myself over decades so much into it that I believe it was from Klausewitz.

So it’s very odd how our memory is shifting and shaping its own world, shaping its own quotations from books.

But it’s the deepest of all question, does the Internet dream of itself. And you can extend it, does artificial intelligence dream of itself, and that’s where it gets interesting.

The Herzog of YouTube

I’d be curious to know if there is a “Herzog of YouTube”. Famous YouTuber Tim Scott did some blimp stuff too, and obviously he has different goals than Herzog, but this A vs B is interesting to me.

Subscribe now

Next thing I knew, my Twitter feed was full of this:

I hadn’t seen any NBA ones yet, so I figured I would give it a try. It was so easy.

Some of them failed in the classic missing appendages way, but if you point it out to the model it can usually fix it on the next try.

Other times it struggled with the surprising physicality of NBA players. Even in the cartoonish world of Miyazaki, Manute Bol and Muggsy Bogues are hard to believe.

But you can get there with a few nudges.

I dumped the full album of pictures that went well on imgur.

The most disappointing case was Drexler at the dunk contest.

He’s in such a unique pose, and the model just can’t get it’s head around it. Way out of the training distribution.

With some tweaking it gets worse…

… before it gets better. But never really good enough to capture the vibe of the incredible source material.

Lebron and Wade’s iconic shot in Miami is another one that just didn’t come out right no matter how much tweaking I did.

But at least it was kinda funny…

I liked it a lot, though I liked The Wild Robot even more (I haven't seen any of the others, no spoilers ahead). For me, Flow’s great achievement is that it has two different characters who felt simultaneously novel and mythic, which seems very hard to do!

The first of these innovative characters initially presents as a standard Jesus / Galadriel / Maximus Meridius sort of guy. But whereas this archetype is usually embroiled in a giant societal-scale conflict, Flow focuses its time with this character entirely on day-to-day life — the mundane consequences of irreversibly sacrificed privilege. And he’s not even the main character!

The second mythic sort of character felt absolutely brand new to me, I can think of no parallel from other fiction, and I still feel such a deep resonance with it that I am convinced there has been an “unnamed archetype” lurking below the cultural water waiting for its true name to arrive in this movie. Sort of a very-low-frequency version of a Greek god.

Everything the movie does, it does in two scales at once. An epic larger-than-life scale, and a simultaneous smaller-than-life ship-in-a-bottle. The exaggerated scale of each accentuates the other, making an experience that’s at once more mundane than Seinfeld and (almost but not-quite) more galactic than Interstellar.

We opened with earnings, not let’s talk cost. In terms of production budget, Moana 2 was $150M, Inside Out 2 was $200M, and The Wild Robot was $78M. Flow cost only $4M. Despite this ~50x cost advantage, Flow still has a lower ROI than its fellow award nominees (for now). Hopefully its growing prestige will help it to reach a much bigger audience, although the awful SEO properties of its name are going to cost it dearly. I loved the movie but I don’t understand how the name relates to it at all. “The Cat and The Flood,” boom, you could even buy the .com for $15.

The reason I’m writing about it is because the filmmaking procedure for this movie is (to me) totally novel, and perhaps the best example of a well-executed “waterfall” project I have ever heard of. It also gives some hints at what generative AI is going to let individuals and small teams make. Just as important, generative AI played no role in the film. Just plain-old non-AI GPUs can enable a fanatic to make a feature-length animated movie for a few million dollars that beats Disney and Pixar along some important axes.

Here’s the story: a 17-year-old Latvian guy named Gints Zilbalodis made a 7-minute animated movie called Aqua and put it on his YouTube. It’s a cat, there’s a flood, the cat is afraid of water, a boat drifts by at the last moment and the cat climbs on, the cat has a mystical relationship with a bird that teaches him how to fish, the flood recedes, then a new flood comes. Every shot is the most dramatic shot that 17-year-old Zilbalodis could think of, sort of spamming the dramatic lighting + vignette button.

When he turned 24, Zilbalodis released a feature-length movie called “Away”, which is currently streaming free on Amazon Prime. He wrote and animated the entire thing himself, even wrote the music. Having shown that he could make at least some kind of movie literally by himself (6.7 out of 10 on IMDB with 1,800 voters), he was able to secure a small amount of funding to expand his old “Aqua” short into the feature length movie that just beat Disney, Pixar, and Dreamworks. This was the first time Zilbalodis had ever worked with anybody else in a professional setting! Four million dollars is ~50x too little to make a feature-length animation, but also 100x too much to give to a never-had-a-job 24 year-old! How did he get it? In his own words, “maybe they thought if there’s a big catastrophe and we run out of budget, I might still finish the film myself in some way.”

Subscribe now

There was no catastrophe, but it wasn’t a one-off miracle either. Zilbalodis is going to be able to do this over and over, and other people are too. The first thing to know is that his first feature-length movie, Away, was rendered in realtime! He basically just screencapped the preview window in Maya! And it’s beautiful!

For his second feature film, Flow, he once again sort of did the entire movie himself, but this time he only made rough environments and animatics. Since he was no longer responsible for character-level animation, Zilbalodis “didn’t limit myself this time, setting it around things that are easy to animate.” The difference between a solo auteur and $4M of skilled human labor and taste is this:

I don’t mean to diminish the human contributions of the ~fifty people who earned the $4 million. Zilbalodis certainly doesn’t! The film was cowritten by Matiss Kaza, and the character animation plays a huge role in the emotional impact of the film. But listen to how they did it, in Zilbalodis’ words (he was 24 when this project started, but now he is 30):

(from 3DVF interview)… the team was quite young. Again, we didn't have a huge budget so we had to find creative ways. So a lot of the team, for them it was one of the first projects they've done. And I think that helped also the film because the team was very passionate. For me it was also less intimidating. We were all kind of at a similar age. I didn't feel kind of afraid of working with these established professionals.

…I did the animatic myself and we didn't do any storyboards. …Basically when I'm doing the animatic I create a rough version of the environment. Very Simple. And I explore the environment with this virtual camera and I look for ideas and find shots. I discover things. I know that some artists and some filmmakers, they can really visualize the scenes in their head. But I don't have this ability. I have to discover them. And once I have figured out the camera, we only do the concept art later. And we design the things that are really visible in the camera. So we don't spend any resources on things that will not be in the frame. And we only put detail on the things that are in the foreground. We don't design something that's far away. Everything is designed from the point of view of the camera.

It’s almost the opposite of George Lucas and Star Wars. Instead of a world looking for an excuse to tell a story, it’s a story conjuring up just enough world to get by.

But lots of studios (maybe all other feature animation studios?) use storyboards, which do exactly that - isolate the work of the story from the work of everything else. What’s unique here is that Zilbalodis binds and entangles the story with the camera motion and set design, very early on in the process. Relative to a team batting around a story board, this is a tightly constrained process. But from the perspective of editing and camerawork, it is incredibly freeing. And it shows!

(from Next Best Picture)… And sometimes I might start a shot and it will be just five seconds long, but sometimes I have these ideas and … almost like a stream of conscious … keeps growing and ends up being five minutes long and the camera is following these characters and that's really difficult to draw as well where the the perspective keep changing so much and … it's almost like this dance between the camera and the characters, and having these longer takes it really helps that immersive aspect where you're feeling very close to the characters. You're not observing them from a distance, and you can … create this subjective point of view.

These “stream of consciousness” shots are the sort of thing that a storyboard would kill. The approach is not without its downsides - there are definitely aspects that feel amateurish. The throughline of the movie is incredibly cohesive, but there are some “side groups” who don’t make much sense to me. It might be that I just don’t get it, but I also think that at Disney they’d have a whole team designing the world of each side group, and they’ll sacrifice a little cohesion in the primary narrative arc to preserve integrity to all the little worlds it is traveling through. Sure, universe integrity is great for seeding sequels and theme-park spinoffs, but it’s also good for the movie itself too!

Zilbalodis is a special talent, and his movie is worth watching for its own sake. But what I really want to think a little about is - if he used Sora or Runway instead of human animators, what would he have made?

I think some big films, because the team is so big, they might lose some of those imperfections, some of those rough edges which I like. You can feel that they're handmade. I wanted to have this balance where things are intended, everything is intentional, but also there are some moments where it's pure emotion. It's something that you can't really explain, you just have to feel it and experience it.

AI videos certainly do not feel handmade right now. But just like the big AI labs, Zilbalodis trained his animators on YouTube data

So we looked at references for everything, for every small moment. When the cat is turning its head a little bit, we find some references on YouTube.

And just like the big AI labs, you can tell Zilbalodis was also heavily trained by video games. The opening sequence feels a bit like upmastered Tarzan 64, and many reviews of the movie note the videogame vibe. Famed video game designer Hideo Kojima called Flow his “No. 1 animation film of 2024”, and heaped even more praise on Zilbalodis’ earlier pure-solo work Away:

Removing all the dialogues and connecting the movement, color and sound with camera work are the fruit of imagination. Unique sense and mysterious feeling/sensation. The boy's journey and lonely adventure. The beauty and desolation created by eerie silence. These feelings of nostalgia, the unknown "away" feeling, I find it irresistible. This is another "DEATH STRANDING".

As a computer programmer, it is clear that everything about my industry is going to be different because of generative AI. Sure AI can help with our existing workflows, but the real earthquake is that you don’t need those workflows anymore. You can follow totally novel processes to achieve totally novel results. I can see it in my field, and I’m primed to see it in everyone else’s field too. So when I heard about this one guy making whole animated movies himself, it’s sort of grounding to know that, yes, gobs of compute is changing everything. But no, it’s not just AI, and the same novel forces that are shaping video AI (YouTube data and synthetic videos from game engines) are shaping the next generation of human filmmakers too.

Who knows what’s coming next for programmers or animators. But what next for Zilbalodis?

We just finished "Flow" literally days before the premiere in Cannes and I'd never seen it with an audience and that was a big relief to see it in Cannes and when people were laughing at the right places and responding correctly. So it doesn't just means that they understand the film, but it's a more personal feeling that they understand me because it's like a personal story about my own experience and it's a very good feeling to know that you're understood.

… [For my next project] The technique will be a little bit different and I think it's something that's never been done in animation which I will not reveal yet but it's a very ambitious and technically complicated technique.

Places to learn more:

• bluesky, x

• Print interviews - Fast Company, Hollywood Reporter

• YouTube interviews - Janus Films, 3DVF, Next Best Picture

Oozification is the process of recursively replacing systems based on numerous larger building blocks, governed by many rules, with ones based on fewer, smaller building blocks, governed by fewer rules, thereby increasing the number of evolutionary possibilities and lowering the number of evolutionary certainties.

Spoiler alert: Disney rides have fun surprises, and I will spoil one of them. My goal is to explore technology and family vacations, not Disney or theme park fandom.

When you finally reach the front of Mickey’s hour long line, train engineer Goofy pulls his locomotive into the station, and you foolishly board one of the four cars behind him. Together, you chug through green countryside and into a foreboding tunnel, where Mickey accidentally drives his car into a switch lever right as your train is going over the switch. Goofy and his locomotive head left as planned, but you and the other passengers veer right under an ominous “KEEP-OUT” sign.

Right away, each of the four cars start to spin and dart off on their own seemingly random paths through projector-illuminated dioramas. I had not noticed that the train tracks at the station were only paint, so it’s a great subversion of your expectations to realize that it’s not a train after all, and anything can happen. Even the car in front of you isn’t giving any hints.

The unshackled ride designers waste no time showing off what their atomized train can do. One minute you’re bobbing along a river.

Then each car darts into its own wraparound dome to go over a waterfall using a kid-friendly purely visual effect, no physical tilting.

And then you go back to the room you just came out of, except now you’re underwater

The entire ride has exactly three degrees of freedom - x/y translation and rotation. If they really wanted to, the Imagineers could have the ride up and running inside the back five aisles of a Costco. In terms of competitive moat, in a way this ride seems like a big step backwards for Disney’s theme park real estate.

But as long as Florida’s rising wet bulb temperature doesn’t start killing off castmembers faster than Disney can hire them, I bet they’ll be okay. Because the most magical part of the ride is a social experience. A bit after the underwater ordeal, you find yourself in a dance studio led by Daisy the duck.

Like any dance studio, the room has a large mirror so you can see yourself and all the other riders laughing as you waltz and pirouette around each other. Rollercoaster tracks can’t do that!

Disney calls these cars AGVs, for Autonomous Guided Vehicles. The first ones were deployed in 1994 for the “Tower of Terror” ride. These early AGVs move slowly over a simple path, and eventually end up in an elevator where they are pulled up and down, adding a thrilling z-translation to the experience.

In 2014 the AGV technology got an upgrade for Remy’s Ratatouille Adventure, and a further upgrade for 2019’s Star Wars: Rise of the Resistance. The Star Wars ride was so much fun that I don’t want to spoil it, but I think there’s no harm in spilling Ratatouille’s beans. The ride puts four passengers on a small tilting platform above a mouse-shaped AGV. Like the dance scene with Minnie, the Remy ride is inherently social. Each family has become a mouse, and you have assembled into a cooperative pack, frantically dodging boots and oven fires. The tilting platform adds physical cues to make the video projections more convincing.

I assume one of these AGVs costs about as much as a Lamborghini, and they spend a lot of their ride time parked inside small hemispherical theatres, which I couldn’t help but notice was an awfully expensive and frankly low-quality VR headset. So how long until Disneyland gets released on VHS?

In terms of technical capacity, I think it’s underestimated how much of a theme park ride experience the lowly Quest 3 from 2023 can already deliver. UrGamingTechie has a great overview video of some local multiplayer games available for Quest.

They have games where you map out the walls and furniture in your house, then your walls and furniture are replaced by crates and fences as you defend a virtual outdoor fort from invading skeletons. They have games where your house stays where it is, but is filled with virtual items to collectively interact with:

And best of all, they have games where you can draw persistent 3D sculptures around your house. With good enough tracking, this can be the ultimate fusion of drawing on the walls and pillow forts.

Unfortunately, the tracking on a Meta Quest 3 is not good enough for pillow forts. Crawling with your head close to the floor or walls is a worst-case scenario for camera-based tracking, especially if you’re moving from one room to another while you’re doing it. Achieving pillow-fort levels of accuracy is likely going to require prosumer hardware for the foreseeable future, with tedious external tracking beacons scattered around the house, and sensors on the front and back of the user’s head to prevent occlusions.

But with an event-based model like Disneyland, this high-end hardware could be amortized across many “guests” - just like you don’t have to buy your own lamborghini-priced AGV to visit Disneyland. To take a family of four to one of Disney’s midrange hotels for two nights and visit the parks for three days costs $2,500, plus airfare. You can buy four brand new Meta Quest 3’s for $2,000, so if you can share a headset across even just 10 guests before it breaks that leaves plenty of room for upscale hardware.

It’s easy to imagine a deluxe staycation package. You scan your house with your phone, and pay $2,500 to Disney. Friday morning, a box of indoor tracking beacons and Apple Vision Pro’s show up at your doorstep, including an extra in case one breaks. At the platinum level you also get a couple rumble pads for the kids, for when the rocket is taking off or the monster is stomping.

The most promising aspect of VR gaming is how little stagecraft developers are using so far. Take the waterfall trick from earlier. Imagine your family “paddling” a canoe together in the kids’ bedroom. You find a submarine, and paddle towards it. You all climb into the closet, and down you go. Climb out of the closet, and now you are divers, walking around in heavy suits on the ocean floor as Nemo flits between you.

Timon and Pumbaa know everyone’s name, and a faithful digital impersonation of Nathan Lane is cracking context appropriate jokes with you as you eat grubs off the carpet. Nahhhhh, svetingahhhhhh, yagaveech, yaga vah yells Dad as he holds the family dog out over the banister of pride rock. Don’t drop her!!! After a weekend of playing deluxe pillow fort at home, the professional quality headsets and tracking beacons get shipped back to Disney on Monday morning.

This business model looks a lot like where Netflix started - mailing you something to watch, and you mail it back when you’re done. But a magical element of the Disney theme park experience is that so many other families are taking a special day at the same time. When Daisy starts directing you on pirouettes, you’re not just laughing with your family, you’re laughing with the whole theater. And the people in the theater are special - they’ve all just paid thousands of dollars to have a good time, and are eager to realize all of that fun in this special weekend. Disney provides its customer not only with rides, but also a cohort of like-minded families looking for a safe group adventure on that same weekend. Deluxe rental staycations allow a company to recreate these cohorts virtually, creating a social context entirely different from XBox Live at 4pm on a weekday.

Interestingly enough, Netflix is in fact in the process of launching a Disneyland competitor, which it is calling Netflix House. But it is not at your house, it’s just a tenant at existing giant malls. Missed opportunity? Or maybe a testbed - get the stuff to work at their House, and then they’ll mail it to your house later on? They’re certainly not taking direct aim at the Disneyland customer - for better and worse, the average mall patron is a lot more like a weekday XBox Live user than a family happily racking up $2k in debt2 for a single weekend.

When it comes to putting people into a cart and whizzing them around dark tunnels, Disney had an incredible roster of IP even on opening day in 1955. Flying above London as Peter Pan, careening around the darkened countryside in Mr. Toad’s motorcar. But if the stage is your own house, are these the best stars? There was a moment when Mario was a stronger brand than even Mickey3 - the talents of the radio star are often mismatched to the next medium.

Fictional universes where a non-specific home is somehow magical seem like a good bet. Classics like Seinfeld and The Simpsons are deceptively weak, because the specifics of the show’s sets are so iconic but likely too different from your own house. You’ve already spent hours looking into Jerry’s living room, what would be the point of looking out of his couch into the cameras?

Disney’s Encanto on the other hand is perfect, where the magical texture of the house is a star, while the specific layout is unremarkable. In terms of characters, Netflix’s Cory Carson stands out for taking a normal house and filling it with anthropomorphic cars who can interact with normal furniture and appliances.

But as I flip through my kids’ bookshelf, the obvious standout at turning the family home into a magical realm is Neil Gaiman.4 Is your relationship with your kids strong enough to re-enact Coraline?

Probably not. But maybe Wolves in the Walls? The headsets arrive, and your kids eagerly don the headsets as you put tracking beacons in the corners of their room. “Stay in here while I setup the rest of the house”. As the kids gleefully build their virtual pillow fort, they start hearing wolves in the walls, which you conspicuously disbelieve as you setup the beacons in the rest of the house. Now the kids are traversing the house, collecting evidence to prove their case to you. Suddenly it turns out they were right, the wolves do come out of the walls. Can you imagine?

Well, they already built it. Meta adapted Wolves in the Walls back in 2018, but it is for lone VR watchers, not social AR players. You watch the character have an adventure in her house, and help her along. We have the technology for children to have this adventure for themselves, with you, in your house.

This technology is called “Bluey”. In case you haven’t seen it, here’s a screenshot:

As you can clearly see, this is a train. The father dog is the train conductor / engineer / locomotive, and the child dog has an injured cat in urgent need of a vet appointment. Unfortunately for your luxury vinyl plank, there are no reasons why you can’t recreate this scene in your own house. You have the technology! Be the AGV!

In the language of startups, most television and movies are B2C, or business to consumer. Mickey (the Business) has an adventure and you can Consume it. Bluey is unique among TV shows in that the real transaction they’re trying to facilitate is between the adults and children watching the show. Sure, the show is fun, and watching it feels like eating candy, not taking medicine. But after bingeing Bluey, kids aren’t begging to have an action figure, they’re pushing the kitchen chairs into the shape of a taxi and begging you to hop in the backseat to get stuck in imaginary traffic.

Which is one of the secret ingredients of the magic of Disneyland. Waiting in imaginatively constructed traffic, accidentally actualizing relationships between the nearby people who cohabitate in the faraway house as they lean towards the carrot of hyperstimulus on rails. What happens when the hyperstimulus comes off the rails and enters the home? Can this do for childhood homes what Pornhub has done for young romance?

I’m worried about a lot of things, but not that. The problem with porn isn’t hyperstimulus, the problem is transforming the social to the solitary. Having one TV is analagous to taking the family out to the theater. But let that second screen in and shwooop - you’re all in pods trapped in the matrix. Hyperstimuli themselves aren’t bad - generation after generation, the hyperstimuli compound and yet the youth adapt. TVs, phones, Virtual Reality - these are all portals to other places, away from the people around us. Social Augmented Reality is a portal to here, the very place where the people around us are.

Who are these people around us? If any of them are children, how do they relate to the adults that control so much of their life, the adults who sacrifice so much of themselves that these children might be safe and happy? In cases where these questions have unhappy answers, it’s too late to ask them in a straightforward way, you have to play pretend and try-on a different relationship like a costume. And so therapists have come up with a menagerie of Parent-Child Interaction Therapy. Which is a fancy way of saying “potentially fun games which have been promised to taste like medicine”.

When Disneyland first opened, the main complaint reviewers had was “the ride said Peter Pan, but there was no Peter Pan!” Because Walt thought his guests came to be transformed into Peter Pan, but they didn’t want that, they came to watch. So Walt revised all the rides and made sure the star was conspicuously present, removing the burden of even temporary transformation from the audience. And yet, with enough watching, transform we have - so many young people both elevated and disfigured by a yearning for their storybook ending.

It’s not possible to watch a story and not be at least a little changed by it. To perform a story? With your family? In the place where you live? When the headsets get shipped back on Monday morning, the promise of a psychedelic mushroom will seem like truck-stop coffee. But unlike hard drugs, you can snap your visual cortex straight back to reality by removing the headset. But what about your relationships? Will they snap back too? Hopefully? Hopefully not?

We brought stages into our houses a long time ago. Like the girl from The Ring, Mickey Mouse and the very stage he exists within is ready to ooze out of the screen and into our every room. How wonderful if The Most Magical Place on Earth was your own home.

A simple system may or may not work. A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.

This assertion is known as Gall’s law. It implicitly defines “simple system” to mean “a system that may or may not work”. A good example of such a system is a biological cell that senses light. Can the cells on your fingernails detect light? Nope. Broken, doesn’t work. How about the cells at the back of your eyes? Yes! …hopefully. If they work at all, then we can stack complexity on top - sink the cells below a pinhole for angular resolution, make the pinhole diameter adjustable for dynamic range, cover the pinhole with a flexible membrane for near or far focus, wrap that in a cover for protection, put glass and polycarbonate over that for more protection and more focus.

Gall’s law implies that time operates only on complex systems. If you have a system that works, then you can apply some time to it, and if you ensure that it still works at every step along the way, then you have followed the only recipe that can produce a complex system that works. If it ever stops working, there’s no amount of time you can use to get it working again unless you revert back to the last working checkpoint.

But of course, time operates on simple systems too - because the complex systems that originate novel systems are evolving. A good example here is the Wright Flyer - people had tried to make flying machines far more complex than the Wrights’ for a long time, but they hadn’t had high-precision machine shops for very long, and no one had ever had a high-precision machine shop and a wind tunnel before.1

And so, as we refine and accumulate the capacities of our existing complex systems, we find that the space of "simple” working systems - those that simply, magically work - is growing.

The problem with novel simple systems is that they almost never happen2. All our heuristics are tuned for coevolving with other relatively ancient and complex systems that we have already adapted to. So we apply the classic heuristic “it’s like a stochas-” WRONG. STOP STOP STOP. NOTHING IS LIKE ANYTHING ELSE.

You have to take a novel system on its own terms, not in terms of some other thing. But Gall’s Law brings good news! If it’s novel and it works, it’s probably still simple! It hasn’t had enough time to become complex, so it’s not too late to draw it out on a single sheet of paper! For yourself — looking at a blogpost of someone else’s sheet of paper doesn’t count. Yours is the hand that must draw the boxes. What pieces does the system have? How are they connected?

Once you’ve stopped trying to pretend that the necessarily simple novel system isn’t actually simple enough for you to draw, you have a chance to see what it does. Again, on its own terms. Does it perform better or worse than - STOP! STOP STOP STOP! Don’t try to find out if it does better or worse. Just see what it does. If you contemplated the system well enough to draw it, then you already noticed some places where you wanted to poke it. Poke! Empty yourself of all concern for utility, soak yourself in the jiggles of the poke, and let the jiggles evaporate slowly enough for their residue to crystallize undeformed by your preconceptions.

In general, we developers get old and crusty. If you spend thirty years analogizing to what it was like when you were twenty, your world model seizes up. was inventing new programming techniques before you were born, and he can still touch his elbows to his toes without bending his knees. I don’t know the exact cause of your rigor mortis or of his flexibility, but it’s notable how frequently he checks-in on even the simplest aspects of reality.

Oh but you’re too busy making cutting edge webpages to burn time on frivolities like weighing things with a postage scale? THAT IS WHY you ended up in the position of frantically updating derelict webpages. Because you don’t know what anything is! John Carmack keeps inventing the future because he keeps finding out what’s here in the present.

And more than ever, I think what’s going to be here in the present are brand new, simple systems. Thinkpieces and explainers keep trying to tell us what ChatGPT is like, while is on YouTube begging us to just take a couple hours and literally make one. If you’re not gonna do that, at least let show you the actual concrete steps that the LLM is taking.

The problem for our heuristics is that this wave of generative AI systems is so powerful, we assume it must also be complex. The most powerful web browser in the world is an evolution of the last browser. Chrome’s version number has passed a hundred because it has a lineage measured in decades, not years. Its power came from tackling complexity, and complex systems always have some antecedent we can analogize from.

A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.

That law still holds, but the sweet aftertaste of the bitter lesson is that it has never been easier to start over and discover something simple that works. If you enjoyed obsessing over semantic versioning and git branching conventions, I hope you got that all out of your system. It’s true that a 10-year-old SaaS website that works is inevitably found to have evolved from a 9-year-old SaaS website that also worked. But pretty soon you might find that every category leader is inevitably found to be a novel arrangement of novel categories of intelligence. The good news is that they’ll be simple. The bad news is that the process which creates them is going to involve way more abject, unsalvageable failure than most “engineers” signed up for.

And all of the good programming languages are like my mom. They have at least one construct entirely devoted to “if the bad thing happens, then what?” In the best languages, you say “I will tie my shoelace”, and the language says “But what if you scrape your forehead?” And nothing else can happen until you have an answer.

“I won’t scrape my forehead while I -” UNNNNNHANDLED CASE ScrapeForeheadException WHAT IF YOU SCRAPE YOUR FOREHEAD ON LllllLLLine TWELVE THIRTY THIRTY TWO then what? …

One option is to run away to live with Python, who lets you drink Coke for breakfast and shit in the refrigerator.1 But it would be better to be a goodie two shoes and say “dear mommy I will get a bandaid from the cupboard and put on neosporin”. That might work, or maybe she’ll hit you with a nested DrankTheNeosporinException but then you can say “dear mommy I’ll call poison control” and eventually she’ll be satisfied and your shoes will be tied.2

As you age and better grasp the desperate scarcity of time, you will correctly say “I don’t have time for this” and incorrectly you’ll say “just do nothing”. The thing she’s worried about? It won’t happen. So if it does happen, do nothing. (because it won’t happen)

Fast is worth it. But you would be better off proudly eating your boogers at Python’s house than to “do nothing” if you scrape your forehead. Because while your mom may or may not respect you, your computer absolutely does. If you say “do nothing”, then nothing will be done. Shoelace by shoelace, your foreskull will be ground flat like the lucky red crayon that never got lost, and as you commanded, nothing will be done.

If you scrape your forehead while tying your shoes, you should scream. You should panic, and you should thank the wise mommy who gave you a chance to do so.

self.breakfast(can_of("coke"))
self.tie_shoes()
self.shit_in(self.refrigerator)

> tied shoes
>
>
> dysentery
>
> dysentery
>
>
> dysenterydysenterydysenterydysenterydysentery

try {
  tieShoes();
} catch (ScrapeForeheadException e) {
  try (Neosporin n = fromCupboard(Neosporin.class)) {
    bandaid(n);
  } catch (DrankTheNeosporinException e2) {
    callPoisonControl(e2);
  }
}

I recently wanted a horse pulling a cart, but I kept getting horses that were carts.

Even in the image I finally chose, there’s a bit of confusion between the horse’s rear legs and the cart.

The latent space1 is very large, but it is swiss-cheesed with these attractors. If the attractor is exactly what you want, you are in a post-scarcity dreamworld. If the attractor is juuuuuust beside what you want, you’re Tantalus in hell.

The melding of a horse with its cart, like the infamous mangled fingers, are a misunderstanding which will improve with time. But not all of the attractors are misunderstandings.

I recently launched a new open source library for testing software. The library allows software to take a “self portrait”, and you can use that portrait as a baseline against which you can measure future changes. Libraries like this already exist, but mine incorporated a novel “camera and lens” concept which helps developers make the portraits more detailed and expressive.

I started off by asking for “robot taking a selfie with a DSLR”, and quickly found two attractor basins. One basin was “take a picture of itself” means “selfie”, and “selfie” means “phone”. The second basin was “DSLRs and robots have the same texture”. Every image either ignored the DSLR part of the prompt, or it morphed the entire robot into a DSLR.

I did not like the implications of a “selfie”. This was a library for rigorous technical software testing, selfies were way too informal. After burning many GPU hours, I stumbled into this image:

It stopped me in my tracks. There was so much inviting whitespace, it practically designed itself.

If I abandoned the point I was aiming for and surrendered to the groove, the bounty was endless.

I could go on - these are not the result of a tasteful selection process, Midjourney drops these like a toddler with a trashbag of m&ms. The “robot selfie” was so easy for the models, we could easily layer other elements and situations. To contrast with the sad “horse and buggy”, we could put the robot in a car:

or the robot could drop its phone mid-selfie for the 404 page.

I had a name picked out already, it’s too embarassing to say but if you search the git history you might find it. When our team realized that somehow selfie.dev was unclaimed, we had no choice - “selfie” it was.

The really strange part is that the library’s features started to change too. We had a feature where every portrait went through something we called a “pipeline”. You could put things into the pipeline to distill a specific facet of the portrait, or compress existing facets into a brief summary. The API was pretty involved, and it felt very much like a “DSLR” feature, not a “selfie” feature.

Now pause for a minute — why was it so easy for the model to draw phone selfies, but hard to draw DSLR selfies? It’s because, in the real world, it is much easier to take a selfie than a DSLR. You can even go so far as to say that phones are better than DSLRs because they have fewer, simpler controls.

So we asked ourselves - could we? The answer was yes2, we could accomplish the same things with fewer, simpler controls. And I swear to god we would not have done that if it weren’t named selfie, and we would never have named our library selfie without the latent space groove we fell into.

I have a narcissistic hoarding compulsion to trademark robots taking selfies. “This thing I have is so good, everyone is going to want it for themselves! And it’s so easy, they’re all going to find it! No! NOO! The robot selfies are all mine, there’s not enough for you to have any!”

But the actual problem is, there are enough! I think that the software artifact we built really is very good, and I don’t want people to confuse it with the other libraries in the market. The medium is the message, and trademarks create the jungle in which the brands roam - take away trademarks and the jungle creatures all ooze into each other.3

Twelve years ago I quit a great job and liquidated my life savings to start a company, and this was the artwork I put on the landing page:

I am not good at this. But with AI, I’m much better!4 This landing page looks pretty cool, right?

I’ve actually been working on three different branding efforts. Selfie was the first one to launch. And the other two I have to scrap because they both got swiped! Stolen! And by stolen, I mean I was scrolling twitter and I saw that someone else had found the exact same groove in which I had been planning on building my brand. Two out of three!

There’s a new domain registry opening up, but this time time there’s no registrar.

The most important function of a test suite is to be a garden of fun starting points (hopefully a wild garden). Want to make a wreath out of orchids? Too bad, orchids are impossible to grow, you’ll never have a wreath’s worth of them. But if you’ve spent the past year cultivating an orchid greenhouse? Sure, make an orchid wreath, weave their petals into orchid-wicker furniture, you can do anything.

The story for most tests is that they pass once, and then continue to pass for as long as anyone is looking. Such tests matter only insomuch as they were fun — which is enough to matter a lot! Look at the colorful tests above - none of them have ever created a red X on a dashboard.

Which gets us to our most important point. Snapshot tests show you what you have. They ask nothing of you, they just show you what is there. And that’s fun! What you actually have is often surprising, and the easier it is to find that out, the better.

Assertions force you to mathematically declare what you want, but nobody cares what you want. The code you are testing doesn’t care what you want. You don’t even know what you want, you’re faking it. When an assertion fails, it says “You don’t have what you claim to want.” Then leaves you to die. With luck you can catch a ride with a println or debugger for a reluctant trip to the “what do I have” store. After making a purchase, the assertion will again tell you whether or not you have what you claim to want. When it fails (again), the assertion will make very little effort (again) to tell you what you have, let alone what you used to have before the assertion started going out of its way to leave you for dead. What you used to have when you were happy is git’s job, get him to do it.

Which is the other magic part of snapshot tests. When a snapshot test starts failing, it doesn’t just show you what you have, it shows you what you used to have too! With a beautiful diff right in the IDE, no git required.

And if you are able to use git, wow! There is so much you can see by watching the history of a snapshot. Here it is, spelled out in plaintext, what you have, not just now, but over time — everything you ever had, and when you had it. With assertions, you can see everything you ever claimed to want, and when you claimed to want it.

If snapshot tests are so great, how come no one uses them?

So if snapshot tests are so great, how come no one uses them? Because everyone is uninterested in what they have, fixated only on what they think they should want. Thusly are they robbed of ever discovering what they actually want, let alone getting any of it!

IDE

Also because everyone runs their tests through their IDE, and they don’t know how to add --updateSnapshot to the ⏵ button. For good reason - it’s impossible!

Lucky for you, there is a new snapshot testing library, selfie, which has figured this out: control comments!1 With selfie, the snapshots are always in read mode. When you want to write the snapshots (like --updateSnapshot), you just put //selfieonce into the source code. When selfie runs, it will update the snapshots and remove the //selfieonce comment so that you’re safely back into read mode. Just smash that ⏵ button, no command line arguments needed!

Another reason people don’t use snapshots is because stale snapshots from deleted tests tend to pile up. Selfie fixes this with precise garbage collection by parsing the test code to determine which snapshots might still be alive, and discreetly eliminating the others.

Of all the reasons people don’t use snapshots, there is only one that is good. People want the text of the test itself to tell a story! (comments don’t count)

• 👍 when <push button> then <html contains “ordered”>.

• 👎 when <push button> then <html equalsSnapshot> // it says ordered, trust me

One solution is to put the snapshot inline with the source code instead of on disk.

• 🤢 when <push button> then <html equalsSnapshot “<html><head><href=’internet stylesheet’></head><div><div><divvyMcDivface><alert><body><span class=”tw:x tw:2 tw:tw">ordered</span>”>.

Good tooling could write the long string for us with all the nice properties of snapshots, but it has low signal to noise. The assertion <text contains “ordered”> is clearly better, even if it will eventually leave us for dead. The solution is to transform the value under test first, and then do the inline snapshot.

• 🤤 when <push button> then <asMarkdown(html) equalsSnapshot “ordered”>

Transforming snapshots in this way is easy to do, and selfie’s lensing features make it especially easy.

Visit an aircraft factory, and you’ll see CNC machines humming along in the kiloflops, tracing precise paths to achieve precise goals. Visit a programmer’s laptop, and you’ll see vomit spattered from shoggoths writhing in the clouds above. The programmer opens the shutter and a deluge of teraflops floods the workspace until the levees orienting the programmer to their task start to creak. The shutter closes and the programmer reorients to aim the next blast of compute as they dynamite their way through conceptual space.

Testing software isn’t about verifying properties anymore, it’s about tailoring a suit for an octopus. Not because the octopus needs a suit; it’s the tailor that needs a map. And the tailor only has one hand - better hand some pins to the octopus!

Rich Hickey is the king of saying simple obvious stuff that is not at all obvious to me until he says it. His latest talk, Design in Practice, is a modest buffet of tips and tricks around a common theme: tight language combined with loose preconceptions can unfold hidden dimensions in which a better design may be possible. Best of all, he comes armed with specific techniques and templates you can use to deliberately push farther along the wordcraft / open-mindedness axes to possibly unlock access to these other dimensions.

The talk is pretty good, but there are two tricks in particular which have been so useful for me that I had to share: glossary and decision matrix.

Glossary

(video at 4:55) Being able to say a lot in a only a few words is a superpower. Being “concise” allows you to make some cuts in pursuit of brevity. Better than that is to be “succinct”, which is brief but still complete. You should name your components with words, if the component changes, the words should change too!

A concrete way to make this advice actually happen in a project is to use a Glossary (video at 8:41). Have one place where the project’s terms can be declared and discussed. The tiny little revolution he introduced for me here is when a term breaks, fix it or abandon it.

In a private codebase I maintain, we had a thing which maintained a basket of software licenses for a single customer. We called this thing a “renewal”, and the basket in question could be a trial, a monthly renewal, or an annual renewal. We introduced a glossary, which gave us a coordinating mechanism to rename this basket to a “flock”, and we nuked “monthly/annual renewal” with “monthly/annual subscription”. Nothing about the CPU instructions of our code changed, just a few human-only names. But all of this code which had long felt vague was suddenly crystal clear, just by deliberately purging the duplicitous “renewal” and replacing it with more precise words. (“Pre-cise” once meant “before cut” by the way, and it is such a luxury in software that even if we didn’t measure twice, we still get a chance to reglue and try a new cut.)

I just started using a glossary in Spotless (#2008) and the upcoming Selfie (#104). I set the glossary as the first pinned issue, and the top comment of the issue is the current glossary. Discussions on the issue have their final result edited into the top comment, and then the discussion is deleted or archived.

Decision matrix

(video at 39:10) What is the fastest stroke for swimming on the moon? An experienced swimmer would probably go straight to freestyle. But the real answer is to run across on top of the water - you can do that on the moon!

Whenever we consider a problem, we will always relate it to similar problems we have solved before. Swimming on earth, our power to weight ratio is so low that we inevitably sink to the waterline - the only strokes we can use are strokes where the largest force is just buoyancy, so we put all our power (physical and imaginal) into forward motion with the assumption that ~all of our body is in the water. But if you pay careful attention, you’ll find an ongoing debate about whether it’s best to swim high or low in the water. It’s such a small difference that ~none of us find a chance to make this choice.

This is a real life hidden dimension, only an inch thick, easy to see but easier to overlook. When you go to the moon, this curled-up dimension expands to your full height, but you’ll only get to use it if you notice that it is there.

The decision matrix is a tool for deliberately finding these dimensions - even creating them! Our perception is involuntarily directed by edges, but we can deliberately drag our mental fingers along a surface to find edges that we might have missed. Let’s go through this exercise for the moon swimming.

As you can see, we put the problem we’re trying to solve in A1. Each column is a potential solution (concise name with a succinct description), and each row is a criterion. The goal of the text is not to judge, it is to describe. When I look at <solution> from <criterion>, what do I see? When I look at <breast stroke> from <drag>, I see high drag as we lift to use the arms followed by ideal low drag for the rest of the stroke.

At some point we will have to make a choice, which involves judging what is good and what is bad, but that is subjective. We should keep this out of the text, because we can put it into colors later - it’s easier to agree on what exists than what is good.

The goal of the decision matrix is not to decide1, the goal is to refactor our understanding of the problem to create space for new solutions. It’s not a shopping list, it’s a combination magnifying glass / dynamite stick.

When we add the butterfly stroke to our matrix, we notice there is a section where a lot of the body is out of the water. On the moon, could we maybe get more of the body out of the water?

When we notice this ridge, we have a chance to say “well, what about just porpoising in and out of the water like a dolphin? What if that is possible?” As we examine dolphin jumping, we see how beneficial it is to be out of the water. The butterfly stroke allowed us to notice that the “depth in water” dimension existed, which leads us to a new porpoising stroke which shows us how much space this dimension has, and now we can design a whole new “stroke” which lives entirely within this newfound dimension.

That’s a toy example, but here’s a real example about read/write control in snapshot testing. Also here’s a template you can copy if you want, though it’s such a simple thing I’m not sure you really need one.

Thanks to the adjustable pedestals, I wouldn’t need the pavers to be very level. Plus, I was building all of this on literal sand, so even if I got the pavers level they weren’t going to stay that way - good thing I can adjust! I started digging in February, and by September it was clear that this was a bad plan.

Sand walks around a bit more than I realized, but its motion is surmountable. What is not, is figuring out where the sand even is. I made no useful progress until October, when I finally screwed some lumber into a big floppy rectangle “retaining wall” bigger than the outside of the pavers, and started shoveling the sand out from that.

It wasn’t important because it kept the sand out, it was important because it told me where the sand was.

Was the sand level? I never did find out, really. But! Was the top of the retaining frame level? Yes! And, did I dig down flush with the bottom of the frame? Also yes! So the boundary of the dig is level, and from there it was only the inside I needed to worry about, and even that not very much because the shed walls all stand at the outside. Once the retaining frame was in place, it was shocking how quickly the rest of the shed went up, after making so little progress in the months prior.

I thought that a bubble level would give me a portal into the infinite fields of Level which surround us at all times. True enough, the Level gods spoke promptly and inexhaustibly through my buoyant oracle. But knitting these answers into something coherent was impossible until I could pin them onto a frame. A frame which took twenty minutes to build, but most of a year to even conceive of trying to build.

It’s almost tautologic to take a frame for granted. How do you find a missing frame? Heck if I know.1

But each night, I slept with my family, Inside, in our house. And it was remarkable how messy that house got as it underwent this little mitosis event to birth a new Inside. And even more remarkable that as soon as I had placed four boards on the ground, meeting only the feeblest definition of Inside, the rest of the shed relatively erupted out of the enclosed area.

I find myself now looking for all the other featureless plains that I’m wandering on accident. Looking for places to drive a stake. Or at least recipes for a raft that can be assembled in midair, referenced only to itself, but sturdy enough to hold a problem safely Inside. We’re all sitting upon and within dozens of such frames already, right now, what’s one more?

For example, let’s say you invent concrete 1.0, a product where people can pour a liquid into a mold, and it will harden like a rock. Very useful for making floors!

But to make a wall with it, people have to build a giant mold to pour it into, and then the whole mold gets thrown away afterwards. What a waste!

But then, a breakthrough! You build a factory full of molds in the shape of large blocks, and pour the liquid yourself. Now people can just stack the solid blocks to the heavens, no molds required!

So what is this, a new feature for concrete? concrete 1.1? No, of course not. You can’t pour it anymore, this is a breaking change. concrete 2.0.

Numbers are not the only sound

Concrete is a sound, it roughly means “pour this liquid and it will become a rock”. One, two, one point two are also sounds, and they roughly mean that you need to learn that there is more to communicating with other people than counting the number of ideas you personally have had. Other people are not counting your ideas, and they’re not impressed by twos or even by ninety-fives.

Tools are literally your body

If you require your users to change the methods and tools that they use, some of them will keep using the old thing. Eventually, many of them will switch to your new thing, possibly even most. But probably the modal user is going to plan to switch at some point, but actually just abandon the project they were using concrete 1.0 on anyway.

This is true, and it is okay. It is okay for you to abandon the old thing, and it is okay for other people to keep using it. But once you release concrete 2.0 and put your marketing and leadership behind it, you severely damage the ability of your users to maintain and improve concrete 1.0 on their own. You permanently break search and tagging for your 1.x hold outs, and even your 2.x users will forever encounter weird non-sensical results at the bottom of their queries, forever.

Your project is probably better than you

Probably your team is bad, and the thing you built is bad also. But maybe the thing you built is good, a lot of people use it, and it matters whether you release a 2.x or launch a new brand. Ask yourself two questions?

• how many things have you made?

• how many of them are good enough that anybody cares what version it is?

Maybe I’m the only idiot, but I have made a lot of things, and there is only one thing that anybody really uses. And it’s quite strange, a mixture of luck and curse that now it’s my job to solve this one weird annoying class of problems for a zillion people.

Are you a genius? Or a monkey with a typewriter? If I’m in a zoo full of monkeys, I’m a genius. But if I’m connected to the internet after it’s had thirty years to spool up? I’m a monkey with a typewriter and a dowsing rod, and if people care what version my thing is, I have found water and I am not so confident in my dowsing skills that I want to force my whole userbase with me into the wilderness to find the next wet spot.

I publishing breaking changes all the time, because I’m an engineer.

But if I’m asking my users to change the methods and tools that they use? Well then I’m gonna find a new name.

Finding a new name

This is not concrete 1.1. Nor is it concrete 2.0.

It’s a cinderblock. Obviously. If I really want to leverage the success of concrete, and emphasize the lineage between my old product and the new, I’m in luck because sounds compose! You can combine them! Don't "preserve" your brand, grow it! Prefix it, suffix it, hyphenate it! All of these operations preserve search and tagging. ConcreteBlocks 1.0, Blok by Concrete.

If you really want to go the "2" route, do it like this: Concrete2 1.0. At least that gives people a chance to tag things #concrete vs #concrete2. But you really lose a lot of information with the brand_preservation_token thing (you lose almost as much as 0.x), and you don't get much (anything?) in return.

And if the difference between #concrete and #concrete2 requires a significant change in methods and tools, then you are really taking two different things and smashing them into one sound, which will never be the best symbol for either of the underlying artifacts. LeTaylor Jameswift might be the both the basketball player and best popstar in history, but they would not sell as many jerseys or albums as their constituent brands could on their own.

It's interesting that there are almost no software projects that version themselves with just 1, 2, 3, 4, 5, 6, etc. Even if you think semver is for space shuttles and not todo apps, you're still not a monster, you wouldn't just call your next version "4". You'll look up the last version you published, guess at what the schema was, and then make number go up more or less depending on how much progress you made since then.

Let's imagine that the progress was enumerated in a hypothetical "changelog", ignoring the detail of whether it's written down or not, and see where it takes us:

• changelog: a list of changes since the last published version

• new version: project these changes, and the absolute level of project quality, onto the three-dimensional vector space of non-negative integers “x.y.z”, path dependent on the previously published three-vector

That sounds silly, but it's not. There are real cultural norms around what level of quality is required to call something “1.0”, what kind of a change is big enough to count as “2.0”, and how silly it would be to publish a “52.0”. You could definitely train a neural net to approximate “version ≈ f (git)”, and the results would feel about right, but I bet the correlations would be surpising. “0.x” probably has less to do with the quality of the code than the quality of the coder’s childhood.

Risk, time, and effort

I have a bicycle. If I gave this bike to a semver-compliant mechanic, they would say one of three things to me when their work was complete:

1. If you don't adjust the way you ride, you will crash.

2. You can ride it the same way, but I added some extra gears you can use if you want.

3. One of the bolts was loose, so I tightened it.

Obviously, (1) is a more important message than (2) or (3). A more subtle distinction is that (2) has more risk than (3). Even the best mechanics aren't perfect, and it's more likely that they made a mistake installing a whole new system than if they only tightened a loose bolt.

From opinion to fact

For millennia, people described temperature as: freezing, cold, warm, hot, boiling, melting. Even today, that's the scale that I use. Does my kid need a jacket if it's 65°F? I have no idea. But if it's cold? Yes, they need a jacket if it's cold.

It’s a funny thing, because we really couldn’t do better than this for a very, very long time, until 1701 when Newton’s anti-fraud work at the Royal Mint led him to invent an apparatus and absolute scale1 for measuring the “degrees of heat” at which various metals melted.

Project quality is a bit like temperature. Cold : bad :: warm : good, etc. And numbers are better than words, so programmers have defined 0.x to mean bad, and 1.x to mean good. Like everything made by programmers, it goes from 0 to 1 with no meaningful gradations in between. And like every absolute estimate made by programmers, it is useless.

From subjective absolute to objective relative

Temperature has two great properties - it is objective (everyone gets the same answer) and it is absolute (you can just say “50F”, you aren’t forced to say “30F hotter than the thing next to it”).

Many programmers are tempted to make their version numbers absolute by defining the version as either 0.x (bad quality / unstable) or 1.x (good quality / stable). But in so doing, they make their version number subjective.

We have had objective units of length for many millennia, and so we have pyramids and temples which are thousands of years old. But we didn’t have an objective measure of temperature until 1700, and it just so happens that we started harnessing thermal power on an exponential singularity curve almost immediately after that.

So if you have to choose to build your house on a subjective or an objective foundation, I would advise you choose the latter. Even if it means trading absolute for relative.

Because we have right now, today, an objective and standardized scale which describes how a dynamic system intended for usage by humans has changed. This system allows a human to take any two versions from any point in the history of the system, and trivially calculate, in their head

• whether integration work will be required or optional

• whether new capabilities will be available

• relative integration risk

And you slump sideways in your ergonomic chair, not using semver, but nevertheless putting massive and unsure effort in an attempt to project a subjective measure of absolute quality into a number? When you could instead trivially assign that number using an objective measure of relative quality? Only programmers and LLMs waste time putting numbers on subjective assessments, but at least LLMs are improving over time.

Version can be a pure function of the changelog

Far and wide, projects have versioning systems that are bad. And yet, a lot of software is good. So apparently I’ve wasted your time, and versions don’t matter that much. But changelogs absolutely do. And there are a lot of projects in MavenCentral and NPM which have no changelogs, but every single one of them has versions.

It's the opposite of what you want! The meaningful thing? Optional. The ambiguous, often meaningless thing? REQUIRED. If there's only enough energy to do one thing, spend it all on the changelog! As Julius Caesar said at the RubyConf in 49BC: The changelog is cast, let the versions fall where they may.

If all you have are version numbers, all you can guess at is the psychology of the authors. But if you have a changelog, then you can calculate Good Version Numbers automatically:

There is some disagreement over how to name the digits in x.y.z. I'm going to use breaking.added.fixed. If you're using the standard keepachangelog format, it is a trivial computation to turn a changelog into a version bump.

## [Unreleased]
### Added
- `foo()` can now accept `bar` as an input
- **BREAKING** you now have to call `fooInit()` before any call to `foo()`

## [3.1.4] - 2020-01-02
...

When it comes time to cut a release, just follow this algorithm:

• Find \n## [Unreleased]

• Scan from there until you find \n## [x.y.z] - yyyy-mm-dd, which will be the last published version.

• Within that string that you just extracted

  • Can you find **BREAKING**? If so, bump breaking, which functions as a concise compatibility guarantee.

  • Else, can you find \n### Added? If so, bump added, which functions as a new feature advertisement.

  • Else, bump fixed, which functions as a signal of low integration risk.

If you happen to be using the JVM, Spotless Changelog has implemented this dead simple logic as a library and also as a gradle plugin. CONTENT MARKETING BABY, THATS HOW YOU DO IT. THATS HOW YOU GET THE STARS.

Pre-1.0, 0.x, and other forms of performative insecurity

As we just showed, one of the things your version can easily be is (concise compatibility guarantee).(new feature advertisement).(lowest downside risk to upgrade), but that is an unpopular way for authors to pick their version. The most popular way to use the version string is to communicate that the author holds their code (or at least its public API) in low regard. Across all of NPM in 2014:

• 82% of packages are maintained by impostor syndromes publishing as 0.x

• 14% of packages are maintained by Dunning-Krugers who publish as 1.x

• 3% of packages are maintained by engineers, with a wide-spectrum of self-confidence, who nonetheless turn the crank and publish (concise compatibility guarantee).(new feature advertisement).(lowest downside risk to upgrade)

If a library has a version, and no one depends on it, does it even have a version? Who cares! But once someone has decided to use your library as a dependency, who cares how good you think it is. Your user(s?) thinks that it's good! Or at least good enough. The terrible thing about “0.x” is that the more unstable a codebase is, the more valuable (concise compatibility guarantee).(new feature advertisement).(lowest downside risk to upgrade) would be!

But habits are what they are, and you're going to keep publishing things with 0.x. I will judge you for that, but Spotless Changelog won't. It will just increment the “added” version (“0.1.0”, “0.2.0”, “0.3.0”, etc) whether your changelog has **BREAKING** or just ### Added. In terms of 3D vector space, this is exactly analagous to smashing an R.G.B image into 0.R+G.B.

But in terms of information content, it's far worse. The 0.R+G.B image transformation preserves intensity information, which is by far the most important signal in vision. But the 0.breaking+added.fixed loses compatibility information, which is by far the most important signal in a version string. For an information content analogue, we have to remove intensity information from the image2.

One of the few good usecases for 0.x is to make sure that the publish process is actually working. But once you've got that working, it's time for 1.x. If nobody else uses it, then it doesn't matter what you picked. And if they do, they're better off if you're giving them semver. This is how solemn the 0.x to 1.x should feel:

In summary

• Changelogs are more useful than versions.

• It is easy to remove an unnecessary degree of freedom by setting version = f(changelog).

• This constraint lets you ignore versions, which don't matter very much.

• This constraint will force your versions to have more information in them.

• This constraint will better conceal your embarrassing insecurity.

  ---

  Discussion on reddit.

  Want more like this, hot off the press?