A constant variable.

Life is, love is, work is.

Things change, perpetually.

Change is frightening but it’s good. We idealize it and rarely realize how tedious it is until we face it.

The universe is nothing but change. Unstoppable, beautiful, change.

Science brought us tools to understand the universe and ourselves.

Out of these tools emerged the Internet, a tool originally designed to help scientists pool their efforts and communicate. One of these scientists, Tim Berners-Lee of CERN, decided in 1989 that it would be a great idea to take the concept of hypertext and apply it to the network in order to create the World Wide Web.

The web changed everything.

And few people understood the ramifications of that change until recently. Most people still don’t.

We do. We have imagination. We think, design, and build. We won’t let other’s lack of imagination stand in the way of our ideas. We make change real by creating tools and products that make people’s lives — and their jobs — easier, more efficient, and fun.

Change is a prism. It reveals things in ourselves that we either ignore or avoid. But the constant variable never fails.

I was ready for this year to bring a lot of change. And it delivered all along the spectrum. But looking out of the window on the last day of the year — annoyed to have posted once a year for the fourth year in a row — I feel proud and grateful of all that we accomplished in the face of relentless adversity.

This year’s changes were multi-faceted: overdue, scary, frustrating, hopeful, tentative, bold.

After years of resisting change, my partner Tamar and I managed to find peace in a new city we’d struggled to call home, bought a house there, and finally our little family is all in one place for the first time in years.

I attended a (gigtantic and fascinating) speech-language pathology conference with Tamar this year. She worked so hard this year: treating patients at the hospital, pushing her Ph.D. forward, learning how to run a pottery studio, and taking care of her family. Much of this would feel impossible to withstand without the best of partners.

Loved ones had to deal with the brunt of negative change this year, but thankfully things eventually improved for many of them. Shocking disease was tackled and tamed with immense group effort; challenging new horizons were explored yielding much-deserved accomplishments and renewed self-worth; and despite the looming shadow of the pandemic’s long tail we found time to discover and rediscover new things and places together.

On the work side, I received the title of Principal Engineer at Pluralsight. Although it took months to feel like I’d earned it. Despite many letdowns over the years, I’ve grown intensely proud of the work my team and I have done to reshape the company for a multi-modal world.

This year, Shields turned 10. I think it’s safe to say no project I started is likely to have the reach this tiny key-value badge has had. I still delight in finding Shields badges on so many open source project repositories across the web.

Maybe I’ll manage to wrap up Keep a Changelog 2.0 in 2024, who knows? 😅 This year marked the 25th language translation for it. While the reach of Shields may be broader, I can’t believe how deep into the world this “little” project — which turned 8 this year — has gone.

Back in November 20, 2013 and December 21st, 2013 I wrote in I’m an Alien. and I need to write. about my then expiring F-1 OPT visa. It now feels like a lifetime ago. I ended up spending five long years back in Paris. There was good in those years, but also quite a lot of bad. It’s not until 2019 that I made my way back to the U.S. with an H-1B visa.

A lot of what I said in “I need to write” was indeed pivotal. While my voice and contributions didn’t carry me professionally through these years, they sustained my spirit. Having a place in the Ruby community gave me friends and acquaintances to grow along with. People with different context than my co-workers, who I could confide in, and ask for help. I’m thankful for the countless times people lent me a hand along the way.

In July 2023 I finally received a permanent residency in the U.S. That was 12 years after I graduated from a U.S. university with an F-1 student visa. You’ve likely heard of people who managed to do this faster. Please think of the many others who are waiting after countless years, at the whims of tech barons, politicians, and voters. Immigration is a constant variable. It scares us to think our countries change outside our control. But countries are always changing. We can evolve with our environment, as long as we embrace this constant variable.

Before the pandemic even started, remote work was already on the rise around the world because it makes sense. Knowledge work doesn’t need to depend on crammed, loud, and unhealthy open offices located in expensive areas devoid of affordable housing. Bringing a laptop to a room inside of a building you spend hours to travel to every day is the definition of absurdity.

Instead working remotely has become almost normal, except to corporate leaders who prefer portraying it as “working from home” as if you need to be grateful for the (temporary) perk. This patronizing butts-in-seats mentality assumes that you’re not, you’re working from home. Perhaps you’re really doing laundry or running errands, but not actually “working”. This ignores the fact that work is already remote by nature when it happens on the Internet. Large organizations effectively have remote offices. They coordinate work across cities and countries. Remote work is here, it’s just not evenly distributed.

Remote Shell Shock

One of the first complaints from first-time remote workers in the spring of 2020 when the pandemic led to an abrupt exodus from shared offices all over the world: it’s hard to communicate remotely.

No shit.

It’s hard to communicate. Period. It was already hard for every remote worker who had to communicate with clustered workers crammed in loud conference rooms, often in blatant violation of fire codes. It’s only now more obvious to everyone how difficult it was for the remote workers to communicate before.

I was one of the first fully remote workers at my job back in 2013. One month I was happily commuting at least three days a week to our Orlando office, the next I was planning a move back to France. I set up shop as an independent contractor in my 30 square meters (330 sq ft) studio in Paris, six timezones away. My manager at the time was clear: be loud about any friction you encounter, we want to make this work and you’re going to be the canary in the coal mine.

Bad Meeting Habits

Quickly, I realized our stand-up meetings where quite awful remotely. A dozen people standing in a circle in a large open space, talking in turn about what they’re working on, doesn’t quite work. Especially with distant webcam and a weak microphone. Soon, folks volunteered to pass a laptop around so I could hear better. We worked on our own laptops all day long but somehow crowded around one to give each other updates. It’s obvious in hindsight that too many people were involved, but it was easy to overlook the issue in person. We soon reduced the size of teams which needed to share frequent updates. I partially credit remote communication for accelerating this realization. Standups later became video calls were each person used their own machine, making everyone as visible and audible, wherever they worked.

It’s hard to say that I thrived working 7253 kilometers away from my co-workers, but somehow, I managed. I enacted a personal policy that has persisted ever since, sometimes I surmise to the annoyance of my more microphone or camera shy co-workers: any non-binary (yes or no) answer should lead to an audio or video call so that context can be provided much faster than through back and forth text-based chat. Any demonstration should be done over screensharing or recorded (and edited) screencast, not with lazily put together step-by-step instructions. That’s because there are always missing steps, and you never identify them when you’re writing them down. You waste other people’s time instead.

The Before Times

By definition being remote means not being there. But feeling present goes a long way. A simple look can trigger a strong reaction and a sense of shared understanding. A slight change in intonation can convey doubt or excitement better than a paragraph. Cameras can’t magically make your expressions visible when light isn’t bouncing off your face. Backlighting or contre-jour for example is a very common mistake that I see very smart people make over and over again, even during important video calls featuring very important people you’d assume would have staff to assist them.

When I moved back to Paris in 2014, I purchased my first Logitech C920 720p webcam. Since I was also co-hosting a podcast at the time, I did some microphone research and bought an absurdly expensive but oh so great Shure SM7B microphone, a Scarlett 2i2 XLR to USB interface (to convert the analog signal to USB) and a cheap pre-amplifier. This setup alone allowed me to stand out and be often seen and heard better than many of my in-office co-workers who crowded together in conference rooms and open spaces.

Sensors Aren’t Eyes and Ears

Still, being so remote was challenging. I didn’t know how to set up the audio interface properly. I mistakenly held out on purchasing a good set of studio headphones thinking I had a sense of my own voice’s volume. But a microphone, like a camera, doesn’t have a human perspective on what loud means. It will blast your co-worker’s ears off or sound like you’re far away. If you’re lucky someone will complain that you’re heard to understand. Most people won’t bother. Don’t use a microphone with live feedback without monitoring headphones. The pros do it for a reason.

Your typical headphone microphones don’t count. You’ll only hear other people’s voices when you wear them, not your own. This is even worse with noise cancellation, which gives you less awareness of your own voice’s volume. Even if your voice is a the appropriate level in your environment, you’d be surprised how differently you sound depending on what microphone you’re using and how far away it is from your face.

Comparing Microphone Outputs

Here are three radically different microphones recording the exact same input albeit at different distances from my voice:

Here is a longer demo of the RODE NT-USB microphone where I to demonstrate how useful an articulated boom arm is:

And the cheapest microphone I’ve tested, the Samson Q2U is impressive and like the Rode can work with USB alone. But it can also support an analog XLR to USB interface which can allow you to push the gain (received input volume of the mic) higher and likely get cleaner output as well depending on your audio interface.

As a bonus, here’s are some popular Apple mobile devices frequently used to send audio and video but don’t fare particularly well even when recording directly on-device with the Voice Memos app:

I think these demonstrate how much more present you can sound with a better microphone. I talk in a bit more detail about this and microphone technique in a previous post.

Face Time

Now let’s talk about your face. Apple did something quite meaningful with FaceTime. They put the onus on precisely what makes you miss your family and friends: their face. Not where they happen to be at the time you call them, or the broad context of what’s around them in a horizontal view, but their vertical portrait. Somehow, Apple still manages to produce webcams that are as bad as they were a decade ago. Meanwhile, Apple makes some of the best selfie phone cameras in the world.

I started out with a cheap and reliable webcam: the Logitech C920. It’s from 2012 and outputs only 720p but for nearly a decade this webcam was basically the best out there. Especially given limitations in bandwidth. Later on in the 2010s, webcams manufacturers introduced full HD or 1080p resolution, and eventually 4K. It’s still arguably too much for just showing a small face on a screen. As photo cameras became all about more megapixels, so did webcams. Focusing on raw output size over output quality, especially in low light.

Compared to camera sensors now common in mobile phones, webcams are a decade behind. My friend Justin Searls found a way to use an old iPhone as a webcam and I completely get it. It’s far more practical than the solution I arrived at just before the pandemic: using a Sony A6000 mirrorless camera with an expensive 50mm lens and an Elgato Cam Link 4K acquisition card so I can use a sensor and lens combo no webcam maker can compete with. The strange video you see at the top of this post was filmed with this setup. One that I actively recommended against to any fellow remoter. Particularly folks who aren’t into photography or videography. It’s cumbersome, complex, and requires constant fidgeting to keep the camera on, obtain a consistent color temperature, or prevent automatic focus hunting due to shallow depth of field. Plus you often have to replace the camera’s battery with an adapter so you don’t run out of juice in the middle of a meeting.

Two long years into this pandemic, one of the few companies that seems to have grasped the importance of a quality sensor and lens combo is Elgato, with their (thankfully mic-less) Facecam. But its output is too wide by default and according to Elgato’s own GM it’s best to tweak exposure manually (at least for now). Logitech has been on top of the webcam business for years, and their best offering is the Logitech Brio. A decent camera sensor attached to a overly wide lens better suited for YouTubers than remote workers whose face should be the sole focus, not their fancy backdrops. You can force the 4K Logitech Brio to crop most of the background it defaults to showing so you can display what truly matters — your face — but it takes some futzing with settings which should be unnecessary.

If you watch the above demo I’m curious if you’ll wonder like me why multi-lens setups are so common in modern phones but don’t exist in any webcam. The wide angle default is only appropriate to a minority of webcam users (streamers) while most people would benefit from a narrow 35mm to 50mm lens equivalent that would focus on their face instead of their surroundings.

Generally speaking, I think the Logitech Brio is the best solution for most people given adequate lighting and restricting yourself to the standard non-widescreen mode (I think it’s the default but you can adjust it with the Camera Settings app Logitech provides).

Hardware Recommendations

Updated (2022-02-24): The $99 Key Light Mini was released in February 2022. I’ve had it for only a few days. Its peak brightness is 800 lumen instead of the Key Light Air’s 1600 lumen but I very rarely used the Air at more than 50/70% brightness, so it’s a great way to save $80. It is now my recommendation for lighting. This brings the minimum total cost of my recommended hardware down to $570 from $650.

Here’s a list of gear I recently recommended as an alternative to my own unwieldy custom setup. The minimum budget is more than double the common “$300 remote stipend” reluctantly relinquished by most companies, while they happily purchase snacks, ergonomic chairs, networking equipment, as well as the typical utility and office leasing costs required for in-office workers. This should give you pause.

This kit is one of the simplest to use and most reliable you’ll likely deal with. Yes, you can get find cheaper microphones and cameras if you sacrifice what I believe are essential features:

• flicker-free consistent lighting (no headaches or artifacts)
• croppable video output that focuses on your face, not the room
• narrow pickup microphones with live headphone monitoring
• headphones to hear yourself and avoid noise feedback loops

This list is by no means exhaustive, and yes it’s very different than what I’ve recommended in the past because the world of remote gear is evolving at last. I’d warn you against integrated solutions (all-in-one lighting, camera, microphone) but it’s possible a company like Elgato will come out a solution that does it all pretty well in the future. The most expensive single component is lighting which might surprise you, and you may find cheaper alternatives using LED work lamps with color temperature control but I haven’t tried those out and would only encourage you to get a precise maximum lumen brightness output number before you settle for one. The most powerful LED work lamp I found on Amazon maxed out at 600 lumen, while the Key Light Air goes up to 1400. You won’t need all that brightness but in my experience 800 to 1000 lumen is the sweet spot in most environments.

The one-stop-shop for remote communication gear doesn’t exist quite yet, but even if some of the items listed here you’d communicate remotely with higher fidelity than the large majority of office workers worldwide did before the pandemic. While your three-dimensional presence will never be replaceable, it’s possible for two-way communication to have an unprecendented amount of subtlety.

Remote Presence

I’ve had a much more intricate setup than the one I recommend above since February 2020. I was preparing to author a video course for Pluralsight and wanted to offer students the best possible learning experience. In countless meetings since, often involving leaders far above my paygrade, it’s impossible to count the number of times someone who matters noticed my facial expressions and asked me to share my thoughts, or reached out to me in DMs afterwards to learn about my setup.

I’ll leave you with this unfair example of a quick video demo of my custom setup which I shot a few months ago during a time of the day where the typical webcam is easily drowned out by backlighting especially without some bright and diffused lighting pointed at your face to compensate. I’m being caricaturally animated (although not that much for me) to highlight how much of my tone, facial expressions, and overal feelings you can perceive from this video. This is not edited in any way other than to make the file smaller and more compressed for easier playback on the web. Granted your Internet bandwidth is sufficient (and that’s a big if) and your conferencing software of choice doesn’t overly compress audio and video you’d likely experience something similar on the other end of a call.

An easily overlooked issue when discussing putting your face on camera is that some folks may not be comfortable or even willing to be seen inside their remote working location (home or otherwise). Especially in larger meetings where they don’t expect to intervene. I don’t think it’s anyone’s duty to always have a high quality camera on. That kind of visibility is clearly not comfortable for everyone but I think within reason — when not using chat or asynchronous messaging — it’s extremely valuable for all parties.

It’s the responsibility of employers to deploy the kind of budgets already allocated toward in-office communication to remote work equipment. It’s also the role of folks like me (and you) to help educate IT departments and business leaders on hardware solutions that already exist today.

It has become quite absurd to argue that remoteness has to mean becoming a less visible and valued contributor to your organization. I hope this post can help you convince anyone who might still believe that communicating remotely still has to be a pain.

After years of small improvements and two years since the last minor release, Keep a Changelog finally reached version 1.0 today.

What’s new? Well, read the changelog!

In short we have 6 new language translations, simplified version-aware language navigation, much clearer and succinct sections that describe the What, Why, and Who of changelogs, and a lot of refinements.

For people who like clear guidelines, there are now guiding principles that summarize the key components of good changelogs. There’s also a section about changelog bad practices to help your friendly maintainers understand that a git log dump doesn’t helping anyone.

Finally, we now document changelog maintenance details and edge cases in a neat little FAQ section to avoid confusing everybody with specifics upfront.

I’d like to thank the incredibly talented Tyler Fortune for his work on the new visual identity of the project. And of course, I’m incredibly grateful to the many contributors who helped translate this project in 14 different languages.

You can see Tyler’s incredible branding work on his website. His work allowed me to create the kind of strong and clear project website I didn’t have the courage to build back in May 2014 when this project originally started.

PS: I’m looking for help porting the following languages to this new version: Czech, German, Spanish, Italian, Polish, Brazilian Portugese, Russian, Slovenian, Swedish, Turkish, Simplified & Traditional Chinese, and any other language you’d like to contribute.

Here there’s a forest behind us and hills before us. I always come here driving too fast and because they don’t have enough people living here to maintain the road well, I have to slow down.

It’s annoying at first to drive more slowly. You want to go from point A to point B. But when you lower your pace, you start noticing these cracks in the road. They tell the story of the trucks and cars and bikes that slowly beat up the road. That road wasn’t just laying there. It was holding on to this piece of land and that land is not having any of that. The river nearby is pulling it over as it strolls by. The mountain back there is pushing it away as it rolls down.

Things are moving, nothing is really standing still. It takes great care to make it look like things aren’t going anywhere.

That takes me to my friend Claus. Claus was an auto salesman at a Volkswagen dealership for years. He’s Canadian but from Germany and he’s small but packs a punch. I don’t mean that he’s aggressive, no, just that he’s intense. He’s got one of those furious brows that can turn from anger to roaring laughter in a split second. He doesn’t like solving problems, he likes to make them disappear.

Claus was a cook for years after retiring from selling cars. He made French and German food, some of the best I’ve ever eaten. It was delicious and simple and got the job done right. Just like he does. I can still remember the taste and color of his roasted potatoes. The ones he served with his famous Bavette. When I was younger I disliked how many vegatables he mixed into the side, and how he loves to drop a ton of lightly roasted scallions on top of the steak. Now I wish I could go back in time and slap myself for not eating them.

First Claus and his wife Paulette had a restaurant on the side of the highway outside of Ste-Agathe-des-Monts in the 90’s. I mean as far as I know. Then in the naughties, they moved to a fancier location in downtown Ste-Agathe. A super cute place in an old wooden house where they had a wide terrasse and could sit a lot more people.

I have some of the best memories of my life in this place but that’s not what I want to focus on. While he and Paulette had so much of this stuff going on — the whole business of running a restaurant, hiring and firing people, getting provisions for the restaurant, prepping, cleaning, all that shit — he took care of things.

He took care of the old roof on the old house his parents left him. He took care of the concrete pavement on the side of the pool that I vaguely recall him telling me his dad blasted out of the rock with dynamite — that one’s not going anywhere. He took care of the little garden until the fucking forest deer starting eating all his nice zuchinis, tomatoes, and cucumbers, at which point he said “fuck it” and put up an electrical fence around the whole garden. It’s not pretty, but it does the job.

Claus’ basement workshop is a place of wonders. If you care remotely about tools, building stuff or even older houses, you’d fall in love with that place in an instant. There’s even a meat smoker in there, under the house, and the smoke runs out throught same pipe as the chimney above. Or a different pipe, I don’t know for sure.

I mentioned that he’s not a tall man, and I guess his father wasn’t either or I guess he made due because that basement is just tall enough for him. There’s storage everywhere, tools everywhere. A few years ago he even had the old oil tank (Canadian winters, are rough) that was taking up so much space and cut it out of there since electric heating makes a lot more sense these days. Now the place looks like a mini- Batcave.

Beyond impressing on me the value of hard and thoughtful work, Claus and people like him reminds me constantly that him and I are people who like to take care of things. His car is old, but you wouldn’t know it. He knows exactly how to make it last as long as it can possibly last. Rust is a fact of life with winters that harsh, so every summer he sets out time to sand off the rust, repaint the damaged bits, and finish it off with some clear coat. I didn’t even know what clear coat was before he showed me. Now I feel like an idiot for not properly maintaining my car’s clear coat now that it’s starting to age. I could have done a much better job making it last, if I had taken care of things.

I guess what I’m getting at is that it bothers me to see so many people scoffing at how things cost when they don’t even understand that stuff doesn’t last forever. The expensive stuff — at least the one that isn’t a scam — lasts a whole lot longer than the cheap shit but that doesn’t mean it’ll take care of itself. You can throw as much money at the world as you want, it’s not going to freeze time. Metal will fade and rust. Glass will crack and shatter. Even the strongest concrete will shatter and slowly turn back into sand.

And that’s not sad thing. It’s a good thing. Nothing stagnates. Things move under the road. You can’t just live your life prentending it’s somebody else’s problem to tend to the cracks. At some point you’ll have to start patching things up.

A beautiful thing I notice when looking at things people made is to see if I can spot “deviations from the plan”. Everything is aligned and straight in the beginning. Then you notice that water is pooling in that one spot, so you have to pour some new concrete. When gasoline runs out of style you end up having to pull electric cables from the house to the shed where the pump for the pool is. You first start drilling that one beam to pass the cable through it but you realize it’s too low, so you make another hole. And you leave the first one, because the sun is getting low and you have to finish before night.

Those pragmatic alterations are one of the most interesting things you can look at as someone who makes things for a living, or just for fun. How people handled evolving requirements. How the best laid plans always need a little adjustement once reality sets in. Like those fucking deer who couldn’t help but eat the goddamned zuchini.

Rationalizations

What took us so long? Why didn’t we do it faster? Are we just really bad at upgrading things? Do we not care about security? Is it because Rails can’t scale? Or maybe Rails 4 is bad?

No. It was just hard. Because I did it wrong. Because I did it mostly alone. Because I tried to do it too fast, and too slow, and everything in between. Because when a startup like Code School is born people take a lot of shortcuts. They (and I) wrote a lot of terrible code, used a lot of terrible dependencies, hacked together a lot of terrible patches.

Eventually, if those terrible things don’t surface in bugs or build failures, you end up paying the price for them on the upgrade trails. The circuitous, slippery, and depressing paths that you can barely see when you’re riding high on the shiny new Rails.

I didn’t spend most of those two years working on these upgrades, of course. Deplore it if you will, framework upgrades are not always a business priority. In my mind they should be because updating often means avoiding getting the short end of the stick with bug fixes. Most important bug fixes are backported to earlier minor versions of frameworks like Rails — some slip through the cracks.

Over time, the body of knowledge surrounding the software your business depends on the most grows stale. People drop support for the version you use in their test builds. Gems stop trying to fix compatibility issues with it. Framework contributors and maintainers accidentally break or deprecate features you came to rely on. Features you’ll have to rewrite in order to upgrade.

On the scarier side, you don’t realize that you’re missing out on some new security features that — while they wouldn’t require a security release that would be backported to your older version — still leave you and your customers a little less safe than the folks on the bleeding edge.

You hear about performance improvements in your ORM and you eagerly start building internal apps using the new version of the framework in order to giddily confirm that yes — it’s much, much faster. You convince yourself that this internal app side project written in Rails 4 and kept up-to-date with every minor release since will better equip you to upgrade your shining 30,000 line of code monolith — but it won’t. No “greenfield” app can ever allow you to judge how a “reddungeon” app will behave on the upgrade trails.

Things will break deep down at what seems to be the interpreter level. That is, until you notice that a ridiculously ancient version of the antediluvian acts_as_list gem is attempting to pass hilariously unsupported arguments to a core ActiveRecord method.

You start developing a near-animal instinct about what really causes exceptions when reading stacktraces and this instinct betrays you because you’re still not reading the goddamned stacktraces.

Eventually you start reminiscing on the past two years and boil them down to some recommendations that can hopefully prevent good people from spending as much time as you did on those treacherous trails.

Hindsights

1 — Don’t Rush

Don’t rush to update to a new version until at least a month (or two) after a major or minor release because one tenth of your 238 transitive dependencies are not compatible yet or their maintainers still don’t know how to losen dependency constraints. Get a pull request and a build going for sure, but wait until that first bugfix release comes out, and maybe a second one.

2 — Don’t Lag

Don’t wait to update until the following version is released. You will miss out on all the blog posts, GitHub issues, and otherwise fresh conversations of people with similar apps in similar situations and whose experiences you could benefit from. I get that it’s easier for other people to feel the upgrade pain, but it’s time to become a better community citizen. Also your assumption that people who upgrade before you will save you from the weird bugs your app will encounter is flawed. There are always edge cases sitting in the dark waiting for you.

No, I’m not talking about Stranger Things.

3 — Subtract

Do use every single opportunity (Pull Request) to remove code and drop third- party dependencies. Not because they’re evil, but because they will make you wish demogorgons were real and could take some people away for ever to the upside-down world of wheel reinventing.

Seriously though, go watch that show.

4 — New Defaults

Do learn about new framework defaults as early as you possibly can. Before Rails 5, the only ways you could do that was by making new empty apps, or running rails rails:update, or using RailsDiff. But now you have new_framework_defaults.rb and that’s pretty cool.

5 — Don’t Skip

Don’t skip minor versions because you really really want to use ActionCable. First off, MessageBus is probably way better. More importantly, you will miss all the deprecation warnings. You know what happens after a deprecation warning? Shit gets removed. That shit that gets removed will be gone and you will cry because your eyes can’t process this many red dots at once and you will think your eyes are bleeding. Yes. They are.

6 — Mini-majors

Take any opportunity to turn any framework minor version upgrade into a mini-major version upgrade if that makes sense. From watching Rails 4, I knew that Strong Parameters were coming when I upgraded us to Rails 3.2, so I added the strong_parameters and converted our models and controllers before we upgraded to Rails 4 so we would have one less variable to account for.

7 — Changelogs

Always read changelogs. Keep changelogs. Yeah, those Rails release changelogs are not great because they’re all split between indedepent sub-components of the framework that few end-users care about. Yeah, there should be more end-user friendly entries in the Rails Upgrade Guides but they are still very useful and you never know what you might notice and get ready for before it’s time for the big upgrade. Every Monday I get a rundown of the new versions released for every single dependency we have thanks to Gemnasium. Yes, that even includes the dreaded Bower and npm ones.

8 — Breaking News

Read the news. If you’re not subscribed to Ruby Weekly, that’s the very least you could be doing to keep your ear to the ground. Even better, learn about what the Rails core team is working on by reading This Week in Rails or great podcasts like The Bikeshed. You know what your team is currently working on and will work on for the next few months. So why don’t you have the same curiosity when it comes to the people maintaining your most important software dependency? Want to go commando on this one? Go to RubyConf, RailsConf, and great regional Ruby conferences so you can talk to these people. They are really nice and will gladly listen to you, talk to you, and perhaps even empathize with your upgrade pains or fix regressions that affect you in new releases!

9 — Experiment

Play with new versions. I started working on an internal app called Orientation while suffering from Rails 5 envy in late 2012 because I felt we needed a better way to document our knowledge dependencies (sense a theme?). It allowed me to learn what we could benefit from in this new version without having to worry about our dependency baggage and technical debt (yet). While I expected our main application to follow sooner, I was still able to keep Orientation in lockstep with all minor and major releases of Rails, which helped a lot with regards to the previous point.

10 - Blank

There is no tenth point. You make it. Share your upgrade stories; good or bad. They’ll help people like you and me make better and more informed decisions about upgrading. The community will also benefit because we’ll all talk about and work on making the upgrade process a little better with each new release.

This post was inspired by a talk I first gave at the Orlando Ruby Users Group on August 11th.

Want me to share these Rails upgrade battle stories with your company or conference attendees? You can find ways to reach below.

Stay safe, stay upgraded.

Prior to this, we have of course been using an internal changelog to document minor version evolutions but so far this wasn’t properly reflected on the website.

I’ve been impressed with how popular this rant-turned-project¹ has been. It looks like many more people than I’ve ever expected are finding it useful in communities much broader than open source software.

Now that the latest version (0.3.0) is public, it will be much easier to coordinate the translations that have been streaming in steadily over the past year.

If you know anyone who could help translate the project in a new language, please point them to the Translations section in the project README for details on how to contribute.

I’m grateful to all the contributors to this project² but in particular to the following folks for submitting pull requests with translations:

• Tianshuo for the Chinese translation(s)
• Michael Burri for German
• Magnus Österlund for Swedish
• Emre Erkan for Turkish
• Alexandr Borisov for Russian
• Talles L for Brazilian Portugese
• Omar del Real for Spanish

Why Keep a CHANGELOG?

The mission of Keep a CHANGELOG is to help software developers understand the value of purposeful version documentation.

Anyone can try to read a commit log between the software version they’re using and a new one they would like to update to. Few people can understand the meaning of each individual commit, assuming project contributors know how to write good commit messages. Even fewer people can understand what commit is going to break their software because you didn’t bother to properly document the changes in yours.

Open source software is certainly valuable, but without proper documentation you might as well keep it closed. Show that you care about the people you share your software with, keep a changelog.

You should read his entire piece. It’s very enlightening to hear the frustrations of a major open source project maintainer, there’s always a lot to learn about how we could improve things.

Unsemantic Versioning

Jeremy’s gripes are quite valid. It is hard for maintainers to figure out how to communicate about possible breaking changes using merely a number. You want people to not be too afraid of upgrading otherwise you’d have to maintain very old version of your software for decades, yet you want them to be aware of what could break when they do upgrade. It’s hard to get right, but I don’t believe that makes Semantic Versioning entirely worthless. I wish we could learn to voice our concern about problems without threatening to move to another country.

Versioning and change-logging go hand in hand. Versions are much more machine-oriented, or at least they’re much more superficial ways to communicate meaning. Change logs, however, offer essential context about versions so that — regardless of whether the maintainers of the project adhere to Semantic Versioning or not — you (the open source software user) can know what they mean by version 2.0.0:

• Does it introduce a major API rewrite? Check the CHANGELOG.
• Does it reflect the introduction of a single (but important) breaking change in the 1.x branch? Check the CHANGELOG.
• Does it mean that — despite the lack of a breaking change — a sufficient amount of new features were introduced to warrant opening a new “version chapter”. Check the CHANGELOG.

Yes, semantic versioning numbers have low resolution. They can be ambiguous. They can be unclear. This why I believe it’s so essential that maintainers make it a priority to a keep a thorough CHANGELOG. I don’t think you can encode three dot-separated numbers with clearer meaning that actual human language.

Numbers + Language

Over the past few months I’ve been working on guidelines to improve how we log changes in open source projects. I called it keepachangelog.com because I’ve noticed that it’s surprisingly common for some popular projects to not even have a change log.

I don’t mean to pretend that I walked back from the mountain with truth-bearing tablets. I’m asking for help and feedback from the community. That’s because the best guidelines — as with science — are based on consensus.

I don’t really want everyone to agree on what a change log’s filename should be (it’s CHANGELOG, deal with it). No, what I want is to gather the most common and sensible change-logging practices and try to get as many people to use them — reliably, consistently, predictably, boringly.

What I do want is for us to improve open source user experience. I’d like to bias the change log conventions towards sensible practices instead of popular or entrenched practices. Sayings like “we’ve always done it this way” and “everybody else does it that way” are noxious. I want to end the practice of periodically dumping git logs diffs into a file and calling that CHANGELOG. It’s useless handwaving and it’s an insult to users and contributors alike.

Badly Breaking

Now, to get back to versioning, it sucks when tons of things stop working because one library changes its API just enough to cause breakage. Yep, it’s a great opportunity for us to have a much-needed conversation about how we communicate about our open source software. As mentioned on The Changelog, the idea that open source software is a gift to the world can be dangerous.

Publishing open source software is not virtuous in vacuum. There are many parts to a praise-worthy open source project :

• defined use cases
• installation steps
• usage examples
• sensible versioning
• bug reporting infrastructure
• contribution guidelines
• clear licensing
• thorough change log
• up-to-date documentation
• reasonable test suite

Notice how I haven’t even mentioned the actual software? Ask any open source maintainer what they spend most time doing or worrying about? I’d be surprised if many said “the software itself”.

The guidelines I’ve established on keepachangelog.com are based on my experience as a developer. For the past two years I’ve been working on a now nearly four-years old Rails application. We have 76 direct production dependencies on the Ruby side alone. Yes, that is a lot. And those dependencies often have their own dependencies. While we try to spend most of time producing things of value for our customers, I’ve been doing my best to keep these dependencies up-to-date for security releases. But of course we’ve also had to fight dependency rot¹ or simply upgrade smaller dependencies whenever we’ve decided it was worthwhile for us to upgrade one of our Alpha dependencies².

This all means that I’ve been spending a lot of time upgrading things, fixing things that minor (or even patch) versions shouldn’t have broken, searching in vain for CHANGELOGs. This has recently become an easier task thanks to Gemnasium but it’s still very difficult, time consuming, and more importantly it’s time I can spend producing software for our customers.

Should we not have this many dependencies? Sure. Yet, I’d rather take a chance on community-maintained libraries rather than betting that our small team (four people) can produce and maintain some software we have little expertise over (but need regardless). That feels like a much more safer bet, at least for now.

Let’s all try to make our open source project more mindful of their end-users. For instance by offering better information (or metadata) about the projects themselves. I don’t think I’d be the only grateful one around if we infused more meaning in our software.

Resources

Here’s a list of interesting projects I’ve gathered recently and which can help you as an open source contributor improve how your project documents and communicate about changes:

• Semantic Versioning
• Fear-Driven Versioning
• Gemnasium and Vandamme (the CHANGELOG parser they use)
• GitHub Changelog Generator
• gitchangelog
• rf-changelog

If you are aware of more (or better) tools that can help maintainers and contributors produce higher quality change logs, please send me a note and I’ll update this list.

Some of these badges weren’t helpful at all. They looked a lot like stealth advertising for the third-party services powering them. Instead, they could have been focusing on providing actual value first, and profit from people clicking on the badges to discover what was providing this useful info.

Basically, the badges were often neither functionally optimal nor aesthetically pleasing. I saw a missed opportunity there. So, despite my rusty design skills, I hopped into Photoshop. Some time later I emerged with a rage diamond. It was a simple Photoshop file with a badge template that I took the time to design properly: consistent padding, a more legible typeface despite a similar font size, better contrast, softer colors, a more subtle gradient, etc.

I called the project Shields as a nod to one of the greatest TV shows of all time — The Shield — and because in the US, a police officer’s badge is sometimes referred to as their “shield”.

Over time the design for the badge evolved. It became good enough that people started paying attention to my little project. The maintainers of Travis CI, Gemfury, Code Climate, Coveralls, Gittip, Gemnasium, and more became involved. Many of these vendors asked us to design a badge for their service, or for help integrating the design into their service by generating PNG files for them.

After some much needed help from Nicholas Acker with an SVG template, we started toying with the idea of an API that would generate badges on the fly based on a key, a value, and a color. It seemed obvious because people were already implementing their own internal APIs to generate them for their service, why not provide a centralized one and never have to crank out PNGs and SVGs by hand?

One issue that caught us by surprise was how poorly the badges (being PNG bitmaps looked on high density (or “Retina”) displays because none of us had a swanky Retina MacBook Pro at the time. Thankfully Kyle Neath from GitHub chimed in and we quickly came up with a temporary yet satisfying solution.

Thankfully the API idea meshed quite well with the resolution issue because SVG images scale to any resolution and they adapt to the pixel density of the screen. Through a slightly tortuous path that took much longer than we anticipated, less than a year after my original rage diamond people in and around the Shields community converged and shields.io was launched thanks to the help of many contributors including Thaddee Tyl, Mathias Bynens, Chad Whitacre, Nathan Youngman and many more.

This API has yet to be as widely adopted as the original PNG Shields badges have been across much of the open source community, but I consider this second major phase of the project a great success. Adoption of the API is slowed by the fact that many of the services (Travis CI, Code Climate, etc.) for which we originally produced badges have since created and hosted their own versions. They obviously couldn’t wait for us to release this API. Now, many of them understandably don’t want to depend on a third-party API to provide a badge feature to their users, which is understandable.

Until all these services get around to updating their websites and internal badge generation services, we will see inconsistencies because the new SVG badges don’t look exactly the same as the first generation.

I’ve wanted to avoid this since inconsistency is what led to this rage diamond in the first place, but it’s alright. In the end my goal with this project was surpassed by a few lightyears. I’m still amazed when I visit the repos of some of my favorite open source projects and discover that little badge design I put together in Photoshop a year ago.

Shields is also the most successful open source project I’ve ever been involved with in a major way, and for a while it didn’t contain a single line of code. I think design-savvy developers and designers have a lot to contribute to the open source world, and Shields is my proof.

Although the initial impulse for this project was frustration, I think my fellow contributors and I have had a non-negligible impact on the open source community. I’ve spent hours talking back and forth with people involved with the services that fuel the data displayed on the badges. Through these conversations, I’ve convinced nearly all of them to focus on semantic clarity (how the badges are named and the data expressed) and the value they provide to end-users (the people who use and contribute to open source projects).

Even though they break the visual guidelines I had originally established, I couldn’t be more proud of seeing new takes on Shields-style badges like Inch Pages. These folks took the concept and tweaked it in order to display far more dense data than I ever thought possible.

In the end, when I find projects READMEs like the Twitter Gem’s, I’m really happy because there is now so much more valuable metadata available at a glance for someone who’s just discovering the project, or even someone who’s coming back to it.

Shields.io allows open source projects like this to be more transparent and approachable. It also makes it easier to tell what their maintainers care about, by showcasing:

dependencies
code quality
test coverage
donations
build status
version awareness
licensing

My tweet

The good Philip Arndt answered that:

Philip Arndt’s tweet

It’s a fair question since the meaning isn’t self-evident. To me there are two basic circumstances in which you build software:

• the one where you build the software you own
• the one where you build the software somebody else owns

I think it’s reasonable to call the first is “product work” and the second “client work”. It’s true that client work often still caters to an end-user that isn’t directly your client, but with product work you are the owner. There is no interface between you and your end-user.

There’s a certain appeal in the kind of freedom that product work affords. While you trade one client for thousands, it’s much easier to say no to these thousands of clients, even if they’re vocal. It imparts you with much more control over your priority.

I think of people who write software as tool builders. It follows in my mind that a tool builder should know how to construct a better tool. That doesn’t mean the intended users of that tool are clueless about what exactly defines a good tool. It also doesn’t mean that the user of the tool can’t define constraints, requirements and suggestions to whoever builds it for them. Yet, what the user (or customer) pays the tool builder for is their expertise in the crafting of reliable and useful tools.

Now, what do I mean by “product gardener”? Well, just like a tool maker, there is a specific set of variables a gardener has to account for when building and maintaining a garden. When planting something, they need to prepare the ground properly; use the right kind of soil; the right amount of watering. As time goes by, a gardener can’t just sit, enjoy the fruits of their initial labor, and move on to something else. In order for their garden to thrive, they have to follow a discipline. They have to attend to what they’ve planted; every day, every week, every month, every year. If they don’t, well, the product of their labor will disappear. And despite my allergies, I really like gardens, so that makes me sad.

I think this silly analogy helps to outline the tension here. If you’re excited by initial struggles, but tend to find the long-term work of sustaining something to be tedious or unfulfilling, then there’s a good chance you’re not made to be a product gardener. Maybe you’re an explorer, opening new paths for people who couldn’t find or see them before. That doesn’t make you less valuable. Michael Lopp would describe you as a “volatile”, then explain how crucial you can be to an organization’s ability to innovate.

I once thought of myself as this kind of explorer. Somehow, I was able to crank out work from scratch in an afternoon, something I find very difficult to do today. Yet as the years passed by I kept stumbling on half-finished remnants of “good ideas” that had ignited fiery passion from me for a few hours or a few days or a few weeks. But that fire burned too quickly, it exhausted all the fuel. I honestly thought I would never be able to commit to any project that would last more than three or six months.

Then something clicked. Maybe I changed. Somehow, though, I feel like I’ve always had this constant gardener seed inside of me. It was just unfulfilled for a long time because I hadn’t yet found a discipline and an environment where it could blossom.

I think that environment was Envy Labs, and especially Code School. I found a place where I didn’t have to waste energy convincing my peers of things that I felt should be normal. Instead I could focus on my work. Oddly the nature and specific function of my work within Code School has evolved very often over the course of two years. I spent quite some time on support, so I was in direct contact with our end-users and their needs.

I think getting lost in the forest of people who use the tools you build is a rejuvenating experience. At first it might seem noisy. It’s easy to let yourself be swayed by the people that complain the loudest. But eventually a sort of music emerges. You stop hearing the voices of individual people, instead you start sensing a breeze of discontent here, a buzzing of excitement there. In a very cheesy New Age kind of way, you start getting in touch with the nature of your users. A mix contexts, problems and potential solutions.

I could pursue this little metaphor yet further, but I think I’ve planted the seed of that idea firmly at this point. Now, concretely, what it means for us to be product gardeners is that we have to be careful not to lose ourselves by taking on too many tasks at once. Our main task is to sustain what has grown so far, and make sure people remain our priority. We have to accept that we can’t be everywhere at the same time and that sometimes things must die so others can survive.

For example, in the past two years I’ve wanted to go on a rampage and build new features for Code TV, our repository of screencasts: to add @replies and better notifications, a full-text search feature, mark videos as watched only when people watch are done watching them, or provide subtitles and transcripts of all our episodes for people with disabilities or who don’t speak English as a native language.

There are many more things I want to do. But eventually I had to resign myself to the fact that, while I want them, I don’t need to build them right now. Somebody else can, and certainly will.

While talking with our team I often say that we should try to become the owners of whatever makes us lose sleep at night. While unfortunate, the absence of the features I listed above doesn’t make me lose any sleep. But many more things do, and I have to make time for these.

If any of these thoughts made you sit up, shake your fist in the air and yell “YES! That!” at your screen while passers-by raised their eyebrows with concern at your rapidly declining sanity, then I beg you, send me an email, and come help us tend to our little garden.

I knew about LiveReload, an app & browser extension that allows you monitor files and refresh the browser only when needed and I was curious if someone else had used it with Jekyll before so I did a typical Google search: jekyll livereload. The first result was a StackOverlow discussion. Generally those are reliable and to the point but I was attracted by the second result, a personal blog post from Thanasis Polychronakis.

Hard to pass on such an amazing name and the title is right on the nose for what I was looking for.

As soon as the page loaded a slight panic started setting in. This is a feeling I’m extremely familiar with because as a software developer, I basically spend 50% of my time researching how to do or fix something on Google (not kidding, expert-level Google searching should be a job requirement). And once in a while, I come across an apparently well written blog post that looks like it’s the one — it’s going to solve my problem I know it!

And there’s no date anywhere.

I scroll down all the way to the bottom. No date.

Twitter share and follow buttons, but no date.

Mostly irrelevant Disqus comments, but… no date.

The post title with no by-line should have tipped me off but I was hopeful. This is a technical topic involving fast-evolving software on the web. These things change every single day. A blog post about Jekyll written two weeks ago could be obsolete because of a new release. Because this — potentially useful — post isn’t dated I can’t know with confidence that it applies to the same version of Jekyll I’m using.

There’s no way to know — at a glance — that this information isn’t irrelevant and a dead end.

Yes, I can sift through the Disqus comments at the bottom of the page and try to infer based on their dates when the original publication was, but that’s not how it’s supposed to go.

A blog post dedicated to a time-sensitive topic should include:

• the title of the blog post
• the full name (or pseudonym) of the author
• the (absolute) date of publication
• the content of the post itself, hopefully with a reference to the version numbers of all mentioned software

It is possible to customize a Google search to only return pages created during a certain time frame — for instance the last year — but this shouldn’t be necessary.

I’m making an example of Thanasis’ post (say that out loud!) even before I’ve finished reading it because I think nailing little details like this can help a lot of people, not because I’m trying to nitpick him for trying to help.

So remember, if you’re going to publish it, put a date on it.