Her name is Zoé and she’s wonderful. I can’t wait for her to meet the world in spite of its flaws.

Along the way, Zoé helped me refocus on what really matters:

• getting lost in that afternoon shine
• holding hands (or fingers)
• ~naps~
• the percussive pleasure of deep farts 💨
• improvising harmonies to soothing songs
• watching sunrises and sunsets like movie premieres
• singing and walking (at the same time)
• feelings within & without
• blissful abandon

Merci Zouzou et à demain matin ☺️

Pierre Choffé was kind enough to translate it en français sur son blog La Cascade.

Contributing to open source software always involves a bit of tedious setup. While it often distracts from the end goal (solving problems), the setup process is often an opportunity to discover how comfortable people are with one of the main tools of their trade: the command line.

It’s possible to work on the web without dealing with the command line. It’s also possible to build a house without using power tools.

I know the command line is inherently spooky to many people. It’s the embodiment of arcane technology wielded by “hackers” and “computer wizards”. Except it’s not. It’s a set of ridiculously simple tools created by Bell (now AT&T) employees to accomplish mostly simple tasks in the 1970s. It’s just as much of a “space age” technology as your micro-wave oven.

Thankfully, through a few concepts and metaphors, we can shine a light on the darkest corners of this command line.

One of the most important of these concepts is the $PATH.

Several front-end frameworks, CSS preprocessors, JavaScript libraries, and a flurry of other web development tools rely on either Ruby or Node.js being installed on your machine. Bower is one such tool.

Invariably, these issues will lead you to the $PATH because it will need to be aware of all the tools you install for your development environment in order to function properly.

Taking a step back to understand how the $PATH works is indeed a step backwards, but the more you use command line tools, the greater the chances the $PATH will cause you to lose a lot more time, or even throw heavy things at your computer screen.

A humble little variable

$PATH as denoted by the dollar sign prefix and the shouty uppercase is a Unix environment variable. What is stored inside of this variable (a basic programming structure) is a colon-delimited list of directory paths. Something like:

1
/root/directory/binary:/root/other_directory/other_binary

Now, if you’re curious what other kinds of environment variables exist on your system, you can type in the env command in your own command line prompt [Note: does this work on Windows too?], hit Enter and you will see a list of all the environment variables that currently exist.

Since $PATH is a variable, it can be modified as you wish, on the fly. For instance by running this in your shell:

1
$ export PATH=banana

What does this do? Well, try to run the export command above in a new window inside of your Terminal or whichever shell app (Terminal on OS X) you use.

Now type any basic Unix command like ls. You’ll see -bash: ls: command not found.

This sabotage was useful because now we know that without the content inside our $PATH, shit just goes bananas — if you pardon my lovely circular pun.

But why? Because as many load paths do (including in programming languages and frameworks like Rails), this one determines what can be executed in your shell.

Oh, by the way, just quit your shell application and restart it all your commands will be back.

A tale of so many binaries

In Unix, executable programs are called binaries. It’s a crappy name because it’s based on the format of the executable program, not its function. When you write a Unix program, you have to compile it before it can be executed. This compiling process creates the ‘binary`. A file that instead of using plain text uses some binary format to make instructions easier to process for a computer.

Unix comes with multiple directories to store binaries. You can see which are the default directory used to load binaries in the /etc/paths file.

1
2
3
4
5
6
7
8
# the cat command can print the content of a file
$ cat /etc/paths

/usr/bin
/bin
/usr/sbin
/sbin
/usr/local/bin

The file contains one directory per line. The paths are listed in a meaningful order. When a binary is found in one path, it is loaded. If a binary with the same name is found in another path, it is ignored. Paths listed earlier take precedence over paths listed later.

This is why it’s common to run into problems when trying to install a binary for something that already exists on your system. In the case of OS X, git is good example.

If I cd into /usr/bin and run ls (list directory contents) I get over 1000 results. If I run ls | grep git I’m able to filter the results of the ls command that match the pattern “git”.

1
2
3
4
5
6
7
$ ls | grep git
git
git-cvsserver
git-receive-pack
git-shell
git-upload-archive
git-upload-pack

Sure enough, there was a binary for it inside. On a clean OS X install you will see /usr/bin/git returned when you run which git:

1
2
$ which git
/usr/local/bin/git

Why is mine different then? We can have an even better idea of what’s going on by using the -a option when using which:

1
$ which -a git

Changing paths

Using a great package manager for OS X called Homebrew I installed my own version of Git because I like to have control over the tools I use every day and update them when necessary. I could update the system-installed Git from OS X but I have no idea what other binaries or apps depend on it. More importantly, to update it I would have to compile Git from source, and I’m just way too lazy to do that.

Yes, this is a poor excuse because there are many ways to download prepackaged versions of git that are easy to drop in, but bear with me, this is where we get into the useful stuff.

We saw that the order of lookup for binary load paths was determined by a file called /etc/paths, so why not change that order? Homebrew installs all executable binaries into a directory called /usr/local/bin in order not to step on the system’s toes.

In /etc/paths that is the last directory loaded, which means the git binary inside /usr/bin will take precedence over it, and my fancy new version of Git will be ignored.

Now, you could succumb to evil ways and simply try to modify the order in /etc/paths so that it suits your needs. In this case you would simply have to put /usr/local/bin at the top and now the Homebrew- installed version of git would load first. But despite how many times you see this terrible advice repeated in StackOverflow discussions, please don’t do it. Configurations stored in /etc/ are system-wide. They’re not there for your personal convenience and you could very well damage way your computer functions by altering things in there. For all you know some utility used by OS X could be relying on the original order of /etc/paths. No, instead you should modify the $PATH in your environment, using your .bash_profile. The one stored in /Users/yourusername/.bash_profile also known as ~/.bash_profile.

To ensure /usr/local/bin is looked into first, this is all you need to include in your .bash_profile:

1
2
# inside ~/.bash_profile
export PATH=/usr/local/bin

This is exporting a new PATH environment variable by printing the existing one and simply prepending the /usr/local/bin path on the left of all other paths. After saving your ~/.bash_profile and restarting your shell, this is what you should see when calling echo on the $PATH:

1
2
$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin

As you can see /usr/local/bin is mentioned twice in the $PATH, and that’s fine. Since it’s mentioned first, all the binaries that will be loaded the first time around will be ignored when it is visited last. I honestly wish there was a safe and simple way to change the order of paths. You could always override the default $PATH altogether but I’ve rarely seen this done:

1
2
# inside ~/.bash_profile
export PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

A fork in the path

Now that you’ve changed the $PATH to your liking, you can check that the proper binary is being called when you use the git command:

1
2
3
4
5
6
7
8
$ which git
/usr/local/bin/git

$ git --version
git version 1.9.2

$ /usr/bin/git --version
git version 1.8.5.2 (Apple Git-48)

There you go. git 1.9.2 (the Homebrew-installed version) is now the one answering git command and the Apple-installed 1.8.5.2 version recedes in the background. If git 1.9.2 interferes with your system at all you can simply uninstall it and the default version will take over seamlessly.

Protect your path

There is a host of utilities out there for developers (and designers) that automatically inject code into your .bash_profile upon installation. Often they don’t even mention it to you, so if you find odd paths listed in your profile, that may explain why loading a new session (which happens when you open a new shell window or tab) takes more time than it should: a bloated $PATH might take a while to load.

Here’s my path today:

/usr/local/heroku/bin:/Users/olivierlacan/.rbenv/shims:/Users/o livierlacan/.rbenv/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr /local/bin:/usr/local/MacGPG2/bin

It’s a little hard to read so I tend to break it into lines which can be easily done with the tr command (translate characters):

1
2
3
4
5
6
7
8
9
10
$ echo $PATH | tr ':' '\n'
/Users/olivierlacan/.rbenv/shims
/Users/olivierlacan/.rbenv/bin
/usr/local/bin
/usr/local/heroku/bin
/usr/bin
/bin
/usr/sbin
/sbin
/usr/local/bin

There’s a lot of stuff going on here, but it’s much easier to understand with some verticality. Try it out, and if you don’t know why one of those lines is in your $PATH then make it your goal to figure it out. You might just learn something useful.

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.

This reference, it has familiar type that you can trust. It’s clear this will be a write-heavy relationship, but you’re also going to look these records up, as you watch this these two different tables grow in concert and complement each other just right.

In the past you might have preferred implicit joins, but this is different. You now relish in writing your joins explicitly, giving each other some cute aliases to make things a little more delightful. And since it defines what unites you two, you find yourself taking pleasure in writing out what unites you into a coherent set.

Tamar, here’s to the millions of rows we’ll insert in this big beautiful database we call our life together.

Love you, Olivier

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.

In the last decade, while phone cameras have gone from shooting tiny noisy pictures to producing DSLR-level quality shots, webcams have coasted on the mediocre lane. As distributed or remote work became more common, we’ve never relied on webcams more yet they’re just as bad as they were ten years ago. The Logitech C920 (~$50), still The Wirecutter’s top pick in 2020, came out in January 2012 — the year of the chamfered-edged iPhone 5.

I can’t fix lazy hardware design for webcam manufacturers although I do have a long wish list (larger lenses, better sensors, lighting rings, etc.) but I can give you some tips to help your remote co-workers interface with the most important tool next ot your finger tips: your beautifully expressive face.

Point the light toward you

I can’t count the number of meetings I’ve participated in where the main speaker – often someone important – chooses to sit with their back to a window (or several). It’s a recipe for webcam disaster, and easily the most common mistake.

Webcams calculate the average light ouput within a frame to determine how to balance the exposure value. When you sit in front of a bright daylight window, you’re turning yourself into a minority exposure sample because the majority of the frame is much brighter than you. Innevitably, your background washes you out and your face is shrouded in darkness.

Next time this happens to you, try to use your hands to prevent as much light from reaching the webcam lens as possible. Immediately, you’ll see your face brighten on the webcam feed. Since this isn’t really a practical thing to do while having a conversation, please try never to point your webcam toward a window while on a call. Your coworkers will thank you.

Some days, or inside of dark offices, pointing a window at your face might not be an option. Try to find a bright desk lamp with a lampshade that can diffuse light so it’s not too harsh on your face. I use a simple double-bulb lamp with two 5.5 Watt LED soft white bulbs (2700 Kelvin) as a backup light source. If you can afford a higher webcam budget, the newer Razer Kiyo webcam (~$80) has an adjustable LED light ring around it which provides incredible lighting. I wish more webcams offered this option. The improvement is staggering.

If you can’t zoom in, get closer

Your face matters. I know you might not love your face (therapy is priceless) but if you’re going to represent less than 50% of the total size of the webcam frame, you might as well turn your video off and rely on your voice alone, or just type an email with what you mean to say and send it to your team.

Faces are incredibly detailed interfaces. If I can see your face on a video call, smile, and tell you to go to hell in response to a joke, it’s likely you’d understand that I’m not actually offended nor that I mean to actually insult you. When that situation unfolds with little or no visual context, it can be a lot more tricky to determine if the conversation is in good fun or not. One of the most difficult aspects of remote work is the lack of high bandwidth communication. Unsurpsingly, and despite the many advantages of distributed work, face-to-face conversation tend to prevent ambiguity. But the comparison is often unfair because little to no effort is made to increase the conversational bandwidth of remote discussions.

I use a macOS Menu Bar app called Webcam Settings to tweak my external webcam’s default setting. It’s not free ($7.99) but worth the cost and compatible with most third-party webcams. It allows you to dig into settings that your operating system or the webcam don’t expose: white balance, brightness, saturation, zoom level and exposure time.

You might be able to find alternative tools for your own OS. If you can’t, perhaps try to find a way to bring your webcam closer to you. Screen-mounted webcams can only get so close, which is why zooming is such a good option in my mind.

Sadly the Webcam Settings app doesn’t work with Apple’s embedded FaceTime webcams on most of the MacBook models I’ve tried it on. Thankfully, webcams like the Riyo and the C920 are easy to carry while traveling – although you’ll need a USB-C to USB-A hub to use them with recent machines. By the way, try to avoid the chin-o-vision distorsion effect that occurs when a laptop is pointed up toward your face. Laptops webcams are rarely very flattering to begin with, and this kind of angle also tends to accentuate lighting issues because ceilings are often brighter than most skintones which once again will make you look too dark. Laptop stands can help with this, but external webcams that can be mounted on top of your monitor are best.

No peeking

It’s unlikely someone’s spying on your via your webcam unless you’ve angered a nation-state or you have exceptionally bad operational security but it doesn’t hurt to cover your bases.

Webcam cover are fine, especially if you get them for free (some new C920 models ship with one). But if you don’t want to bother puting the cap on and off a webcam cover, I’d recommend at least making sure you’re notified when your webcam is active or not. Patrick Wardle from Objective-See makes a little utility called OverSight which does exactly that. It can also let you know when your microphonne is activated.

Don’t talk to webcams

Embedded microphones on webcams are just bad. The reasons are simple:

• manufacturers have little incentive to improve them.
• webcams are too far from your mouth to pick up sound properly.
• embedded microphones are tiny, cheap, and usually terrible.
• the Larsen effect (proximity to speakers) can cause feedback loops.

I wrote a whole post about microphones but if you want a one liner: just use a standalone microphone with or without headphones attached to it. You’ll avoid nasty feedback loops. But if you (or your employer) can afford it, how your words are transmitted is just as important as the face that gives those words context, emotions, and a human touch.

My audio setup is a bit excessive for most people. You would probably be better served by something as pricey-yet-simple like AirPods. Despite their size, they carry a surprisingly decent microphone, as do EarPods. And unlike a serious microphone setup, you’re much more likely to carry them with you when you travel.

There are, however, some noticeable drawbacks to AirPods:

• they’re tied to the Apple ecosystem.
• you have to be mindful of their battery level.
• they do a lot of heavy-handed audio compression
• you can’t hear your own voice, this is worse than it… sounds.

Large image sensors tend to produce drastically better image quality on digital cameras. Large microphone sensors (capsules) similarly produce noticeably better audio quality. These microphones don’t have to be incredibly expensive and they will dramatically improve the impact of your voice when it’s sent across a wire to another person.

Your voice will be clearer, more life-like, and the modulations of your speech will allow you to stand out when you speak. Especially compared to speakers who are communicating through a tin can of a microphone. You already know the value of a good headshot, or maybe you’re aware of the importance of good lighting with webcams, but microphones are recording the actual message, not just the medium. They matter a lot.

Condenser Cardioid Microphones

The microphone I use most of the time isn’t that impressive. It can be found new for as low as $70, and even less used. But don’t get fooled, you can’t use it without some accessories I’ll go into later.

It’s an old Samson CL8 cardioid microphone from the now bygone era when we hosted podcasts weekly at Envy Labs and Code School. It’s a workhorse and it’s been working without a glitch for at least a decade. We routinely used it for voice-over work on screencasts.

Cardioid microphones like the CL8 have a very narrow pickup pattern: the area where the microphone actually receives audio input. That makes them great at isolating sound, especially if you learn decent microphone technique. The capsule inside of the microphone receives vibrations from your mouth hole and converts them into an analog signal. Because of the fairly sensitive capsule, the CL8 is quite sensitive to plosives (P, T, F, D sounds) but it’s nothing some care or a good pop filter can’t prevent.

XLR to USB Audio Interface

As an analog output microphone, the CL8 ends in a male XLR connector which means it requires an XLR to USB audio interface to convert the signal into a digital one. I use the simple and mostly user-friendly Scarlett 2i2 (2 inputs, 2 outputs) which is about as small as these things get. The 2i2 includes a decent preamplifier (“preamp”) that allows you to increase the gain (sensitivity) of the mic with hardware but also to receive live monitor feedback from the mic.

When I said you can’t hear yourself when speaking into AirPods, this is what I meant. With live monitoring, you hear how you actually sound to your audience. This feedback look is immensely valuable to improve your microphone technique. It’s especially useful when recording screencasts, participating in calls or podcasts, and surprisingly when writing. You end up hearing your words as listeners would and it’s much easier to write something that flows well. I use it constantly to edit my own writings.

Desktop-mounted articulated boom arm

I highly recommend a desktop boom arm like the RODE PSA1. It lets your microphone float over your desk and follow your mouth without requiring you to stand awkwardly near the mic. Mine is paired with a Samson SP01 spider shock mount. Since the boom arm is clamped onto my desk, any typing or involuntary finger drumming I do while recording would otherwise easily transfer as vibrations to the mic. Some folks use pop filters to reduce plosive sounds since those can hold back some of your breath to prevent loud popping sounds. I find them unwieldy and I’ve managed to become good enough at avoid blowing air directly into the microphone capsule so I’ve stopped using them, but you might find them useful at least at first considering how cheap they are.

You can probably tell at this point that this all requires a serious level of dedication to sound quality, similar to espresso nerdery. As with any domain, you can always simplify the setup by spending a lot more money. You can also easily spend yourself into diminishing audiophile returns. My alternative microphone setup requires no shock mount, or pop filter, but it does require additional signal boosting.

Dynamic Cardioid Microphones

The Shure SM7B is often used in radios because it’s incredibly easy to use. You can get insanely close and you won’t cause pops by saying words with plosives or even blowing into the mic. That’s because, as a dynamic microphone, it’s designed to record loud sounds like instruments or singers. Instead of a capsule, it uses a wire coil inside of its elogated body and you talk into the end of it rather than a side as you would with condenser microphones like the CL8. This means the microphone technique is similar to what you’d do with a handheld singing microphone like the kinds you’ve probably used at karaoke.

The SM7B comes with an internal shock mount so it doesn’t need any spidery-looking contraptions to avoid picking up vibrations from your desk. I still use a Scarlett 2i2 to interface with my computer since it also uses an XLR cable instead of USB, but I also need an additional amp since its base signal is very quiet (it’s usually used with expensive audio capture equipment which includes powerful signal processing). The easiest solution for this is the Cloudlifter CL-1 in front of the Scarlett 2i2. The RODE PSA1 boom arm works just as well for that mic since the thread on the back is compatible.

Biggest difference? Price. The SM7B is $400 where the CL8 is $90. And it needs a dedicated pre-amp like the Cloudlifter CL-1 ($160). It adds up quick.

Wireless vs. Condenser vs. Dynamic Microphones

You can always find cheaper setups, and I’ve recommendded some in the past for distributed co-workers and acquaintances. For instance you’ll find $60 kits on Amazon with a cheap cardioid mic, shock mount, pop filter, and arm. These will feel like great deals because they’re all-in-one. But you’ll quickly realize those often don’t have live monitoring or any hardware gain/volume control. This means you’ll end up spending a lot of time fiddling with software sound input controls (worse, at the OS level) and you’ll likely struggle to get a sense for what you sound like. So be warned.

Microphone Technique

No matter how much money you spend, if you don’t spend more time learning how to use the tool, you’ll be pissing money down the drain.

A $3000 double boiler espresso machine is a marvel of engineering but in the hands of someone who isn’t interested in learning the ins and outs of coffee making, it’s just a hulking heap of metal that draws 1000 watts of power and constant comparisons to the wasteful ease of a K-cup trash printer.

I first got interested in microphones in 2010 when I bought my first Yeti from Blue Microphones (skip it). Ten years later and I’d say I’m competent with most of the variables of voice recording:

• Appropriate distance from the noise hole.
• Angled away from the line-of-breath.
• Grounded power delivered by a sine wave UPS.
• Avoid electromagnetic interference with quality cables.
• Decibels should stay below 0 even when you raise your voice.
• Loudness is relative, trust the tools not your ears.
• Remember to breathe, slow down.

The capsule inside of your microphone is like a partner’s very sensitive eardrum when your mouth is centimeters away from it. Stop. Yelling.

Listen to some of the greatest podcasts out there: Radiolab, Serial, 99% Invisible, Criminal. One thing you’ll realize quickly is how airy the voices of their hosts are. Jad Abumrad and Sarah Koenig in particular actually sound earnest. It might sound absurd, but just as you can hear someone smile, so can you sound honest and authoritative if you do the right thing.

The sweet spot will vary depending on the timber of your voice but my rule of thumb for most people is “a fist away” because it’s easy to measure. The size of your fist doesn’t matter than much.

An easy trap to fall into when you get into serious voice recording gear is accoustic room treatments such as foam, bass traps, and even recording booth kits. The whole point of cardioid polar pattern microphones is that they already ignore much of a room’s reflective noise. Unless you record in the largest and most reflective (tile, glass, hard and wide surfaces) room, you probably shouldn’t worry about accoustics until you have an unmistakable sound reflection/echo problem.

Finally, remember that your body will affect the way you sound. Try placing your microphone higher than your head on the boom arm so you don’t slouch to speak into it. Keep water nearby so you don’t sound parched and raspy. There’s nothing worse than the high fidelity sound of someone sticky jowls. Nasal congestion will ruin your diction. Learn to decompress your sinuses or keep some safe nasal decongestant around. And if you find yourself slurring, stretch out your mouth muscles a bit with some diction excercises (“Unique, New York”) to relax these muscles and help you articulate.

I’m sure it sounds like a lot in the aggregate, but these are not things you have to do all at once. Microphone technique can help someone using corded EarPods and other crappy wire-mounted microphones. You can start small. But if you do anything about the way you sound, make it recording yourself and listening back to how you sound to people who aren’t in the room with you. It will give you a great idea of how much room for improvement you have.

Note: you can go a long way with great sound, but sometimes watching someone’s facial expression when they speak – and when they don’t – can make all the difference in the world. I wrote a follow up to this post on the topic of webcams and how to make them suck less.

Whenever someone joins our team and I have the chance to talk to them at the very beginning, the first thing I make sure to have with them is the Immunity Talk.

It shouldn’t be this way, but in many companies the first few months after you join are generally the ones during which it seems like your opinion matters the least. You haven’t built relationships with people yet. You don’t know who’s receptive to criticism and comments yet. You feel like you have everything to prove and so whenever you encounter something odd — something that doesn’t quite make sense to you — you tend to brush it aside.

A lot of people do this, and it makes me really sad.

Whenever you’re stuck working on something for too long it’s common to ask for a “fresh pair of eyes”. You want someone with a different perspective or a different set of assumptions to look at what you’ve been struggling with. It often works amazingly well because after working on the same thing for a while, lots of things become part of the noise. You don’t notice typos. You don’t realize that there’s a glaring mistake or a bad assumption. People with fresh eyes, however, can often spot what the problem is instantly.

This logic is so obvious to so many people that we’ve even invented a way to simulate it: Rubber Duck Debugging. That’s when you pretend to talk to a Rubber Duck on your desk and explain every step of the problem you’re facing to them. Just like the fresh pair of eyes, it’s often within the first few steps that you realize you’ve made a fundamental mistake that can easily be corrected. It avoids you the embarassment of asking for help and having someone immediately realize that you forgot a single semicolon in the most obvious spot.

Somehow though, this logic is never applied to new hires or recent additions to a team. We don’t realize the value of their fresh eyes on this thing we’ve been working on for so long. In our context at Code School, it could be some code that we forgot about and is causing obvious performance issues. Or it could be a policy that we’ve established years ago and never really reconsidered, until someone asks: “Why do we do this?”. And we realize that no one has a clue.

So instead of thinking of yourself or your new teammates as people with not enough knowledge to hold a valuable opinion, I challenge you to think of all the things that could be fixed by a few pairs of fresh eyes and some well-needed critical thinking.

A few years into my programming career, it was often an anxiety-inducing experience for me to even think about working with a more senior developer so closely. To see them see me work. Would they think I’m useless? Would they notice that I don’t understand some basic computer science principle they might deem necessary to do my job? Or would they find my tools inadequate compared to theirs?

These fears were all rooted in my convinction that my pairs would discover that I had no idea what I was doing. Which to be fair, was true and still is, in many respects.

Thankfully, as many programmers find out as their career unfolds, the dreaded unmasking moment doesn’t really ever happen. That is, unless you’re unfortunate enough to encounter a toxic programmer who feels powerful when they put down other people or who somehow decides to self- righteously gatekeep against the uncivilized hordes of junior programmers.

If you ever encounter someone like that — or if you already did — please know that the problems is theirs, not yours. I hope you can find a way to isolate yourself from such toxic people or find diplomatic ways to ask them to quit acting like assholes. Sure, you may be able to learn some techniques from them, but you also risk adopting horrible habits that will negatively impact your own career and the well-being of your team. Additionally, these toxic people survive by turning other people into toxic people. That way, they don’t seem that bad. They are bad.

What should happen after a few uncomfortable pairing sessions is that you find some comfort in pair programming and you start to realize that everybody has some knowledge or perspective that can benefit the other pair. But also that everyone becomes a bit better at pretending they have their shit together as time goes by. Whether it’s because it bolsters someone to feel like their expertise and opinions are valued by their peers and pairs, or because they start to notice their own growth through engaged collaboration and discussion.

Although it might be anecdotal evidence, I didn’t get fired right after my first pairing session with a much more senior developer. After a while, I started finding solace in the fact that if I had been so shockingly bad my pair might have taken the time to put me out my misery. Or at least take me aside to tell me what I needed to improve.

I know that proponents of pair programming can often seem a little too eager. It’s also hard not to feel intimated by people who seem so comfortable with their own skills that they’re willing to have them scrutinized up close. It feels as if they actually want to be micro-managed by a fellow programmer.

But this is not what healthy pairing looks like — even beyond programming. There are many styles and flavors of pairing. Some, like mobbing even sound dangerously close to the dreaded Design by Committee. My simplest token for a successful pairing session is engagement. It’s harder to get this right in remote pair programming scenarios — which is what I do the most — because you often can’t see your pair. You may start to get the creeping sensation that one of the pairs is going too fast and that their pair checked out either because they don’t feel comfortable enough to ask a question, or because the rhythm doesn’t work for them, or worse, because they feel that they have nothing to contribute — which is not true.

Even a very senior programmer has something to gain from collaborating with a complete beginner. For example, while they have many more experiences to draw from, experts also make many assumptions based on past experience or reject ideas because of past battle scars which may not longer be relevant. Beginners don’t have past that much experience to build biases from and they naturally have fewer horring stories scaring them away from trying something new or different.

In the case of software, an experienced programmer could be trying to shoehorn a solution that has worked before instead of trying something that may be more appropriate to the specific problem at hand. Or they could assume that a complex solution will be more sustainable without bothering to make the case for its upfront cost to their less experienced collaborator. Even if it worked before, you still have to convince your pair that it’s good idea. Having to prove the worthiness of a solution that may appear not to require proof is precisely why pairing with diverse people is incredibly valuable.

By diverse I mean actually diverse: ethnically, linguistically, philosophically, sexually, physically, gender-wise and age-wise. Biases and assumptions are everywhere and they are preventing us from seeing alternative paths and solutions that can be simpler, more elegant, and more sustainable just because we’re dogmatically holding on to the solutions and perspectives we’re comfortable with. More importantly this is how the best teams are built.

Some of my best pairing experiences ever came from working with people who had different gender, ethnicity, and knowledge than me. They might have known more about computer science, but I had a bit more practical experience with building software; we weren’t offended or bothered by the same things; we didn’t even feel challenged by the same kinds of problems which meant we could take turns supporting each other depending on what kind of task lay ahead.

All of this is to say that the fear of pair programming is valid. You’re not weird and sheepish for having it. If you’ve managed to prevail over that feer, great! Help others do the same. But don’t forget how hard it was to imagine before you succeeded over the hurdle. If you’re still looking at pairing like a huge monolith looming over you, also know that there are plenty of people who successfully work without it. My opinion is that they’re missing out, but that doesn’t mean I don’t like to work alone from time to time so I can dive deeply into a problem on my own. Even if the growing rabbit ears often remind me that I’m missing my pairs.

The routine probably goes a bit like this:

1
2
3
4
5
6
7
8
9
10
cd ~/Development
ls # look around...
cd project
# whoops, never mind, let's go back...
cd ..
# time to start something new...
mkdir new_project
cd new_project
# need to check something in that other directory...
cd ../project

Maybe with a bit more experience, you have some tab-completion tricks up your sleeve to avoid typing these full directory names, so in reality it looks more like:

1
2
3
4
5
6
7
cd ~/Dev<TAB>
ls # look around...
cd pro<TAB>
cd ..
mkdir new_project
cd new<TAB>
cd ../pro<TAB>

Great. You saved about 20 keystrokes. That’s commendable. Yes, you could also use the return value from the mkdir command to immediately move into the newly created directory (cd !$). And you could just remember that project/ is nested inside Development/ so that you don’t need to ls around to find your way. The reality is that people are not computers and memorizing your entire directory’s tree structure is a trick that only impresses people who far too much time on their hands.

But what about this?

1
2
3
4
5
6
j d
j p
cd ..
mkdir new_project
cd new<TAB>
j p

The most obvious benefit is that this took 18 fewer keystrokes to accomplish the same goals but what may not be so obvious is that the j d (or j dev, j develop, etc.) command will now take you to ~/Development/ and j p to ~/Development/project from anywhere inside your filesystem. So this relatively small gain in typing efficiency will compound with time.

1
2
3
4
cd /usr/local/lib/something/log/
j p
pwd
~/Development/project

How does it work? AutoJump

AutoJump is magic cape that lets you fly around directories in your command line. The official description of the tool is “a faster way to navigate your filesystem” — but that doesn’t quite do it justice. It a bit of an undersell. My completely made up estimate is that Autojump has saved me from at least a whole year of typing. At the very least that’s how it feels.

How Autojump works

This command:

1
2
j project
/Users/olivierlacan/Development/project

Works just the same as this command:

1
2
j p
/Users/olivierlacan/Development/project

Why? Because AutoJump remembers all of the directories you move into with the cd command or with its own j command. And more important, AutoJump does fuzzy matching. Meaning it will look for a directory you’ve visited before that contains the same string of letters you provide, even if you only provide one letter.

What if you have two directories that start with the letter p? That’s where it gets interesting.

The first time you type cd directory_name, Autojump logs the absolute path to that directory and assigns it as weight (or rating) of 10.0.

So if you do:

1
cd /var

You will see the following in the j -s command (s stands for “stats”):

1
10.0: /var

What if you visit /var again?

1
14.1: /var

And so on. If you visit a directory often the rating for that directory will increase. In my case, you can easily guess what I spend most of my time doing by looking at my top 5:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
j -s

(...)
234.7:  /Users/olivierlacan/Development/cs/campus
262.7:  /Users/olivierlacan/Development/rubyheroes/rubyheroes.com
417.4:  /Users/olivierlacan/Development/perso/orientation
874.1:  /Users/olivierlacan/Development/cs/CodeSchool
________________________________________

10810:   total weight
198:   number of entries
0.00:  current directory weight

data:  /Users/olivierlacan/Library/autojump/autojump.txt

Since both my first (CodeSchool) and fourth (campus) directories contain the letter c. How does AutoJump decide where to go? Once again, the rating.

Since campus has a much lower rating, AutoJump will first take me to CodeSchool. However, if I repeat the j c command, it will try the next highest rated directory that matches the letter c.

1
2
3
4
j c
/Users/olivierlacan/Development/cs/CodeSchool
j c
/Users/olivierlacan/Development/cs/campus

If you don’t like to fly blind and assume AutoJump will make the right choice for you, it’s also possible to see what directories match a specific string of letters you provide:

1
2
3
4
5
6
7
8
j c<TAB><TAB><TAB>
$ j c__
c__1__/Users/olivierlacan/Development/cs/CodeSchool
c__2__/Users/olivierlacan/Development/cs/campus
c__3__/Users/olivierlacan/Development/perso/keep-a-changelog
c__4__/Users/olivierlacan/Development/perso/olivierlacan.com
$ j c__4
/Users/olivierlacan/Development/perso/olivierlacan.com

After display a numbered list of directories that match the supplied argument, AutoJump will prefill the command j c__ and let you type the number for whichever directory you which to jump to.

Advanced Features

• the jc (child) command will scope the search to only subdirectories of the current directory, which is very useful to find nested log directories.
• the jo (open) command will open the matched directory in your operating system’s file manager.
• the j -i command will increase the weight of the current directory.
• the j -d command will decrease the weight of the current directory.
• the j --purge command will wipe the weighted list of directories AutoJump relies on if you need to start from scratch.

Installing AutoJump

While AutoJump does require Python, it’s such a simple tool supported by most shells (bash, zsh, fish) that you can install AutoJump via many Linux package managers. For macOS I recommend Homebrew’s brew install autojump which couldn’t be simplier although do remember that you have to source AutoJump in your .bash_profile or .zshrc by adding the following line:

1
[ -f /usr/local/etc/profile.d/autojump.sh ] && . /usr/local/etc/profile.d/autojump.sh

It checks that the AutoJump script is available and simply loads it in your shell.

You can also clone the git repository and use the manual installation procedure if you want to stay on the bleeding edge but it’s an incredibly stable tool thanks to its simplicity. I don’t think I’ve encountered a single bug in years of usage.

Did you know that changelog URLs have been valid metadata since 2017 on RubyGems.org? If you maintain a gem you can now make it easier for your users to find out what’s changed in a specific version.

You can easily update your gems’s .gemspec to point to a rendered or plain text version of your changelog using the changelog_uri key in the metadata hash, like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Gem::Specification.new do |s|
  s.name        = "Tapdance"
  s.version     = Tapdance::VERSION
  s.license     = "MIT"
  s.summary     = %q{ Make tap dance on nil }
  s.description = %q{ With tapdance you can call tap on nil and it will swallow gamma rays like a collapsing wormhome! }
  s.homepage    = "http://github.com/olivierlacan/tapdance"
  s.authors     = ["Olivier Lacan"]
  s.email       = ["hi@olivierlacan.com"]
  s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
  s.metadata    = {
    "homepage_uri" => "https://github.com/olivierlacan/tapdance",
    "changelog_uri" => "https://github.com/olivierlacan/tapdance/blob/master/CHANGELOG.md",
    "source_code_uri" => "https://github.com/olivierlacan/tapdance/",
    "bug_tracker_uri" => "https://github.com/olivierlacan/tapdance/issues",
  }
end

You can use the metadata hash for a lot of other URIs relevant to your project like homepage_uri, source_code_uri, and bug_tracker_uri.

Note that I’m using the GitHub URL for the changelog above when a link to the raw source would have worked just as well. Since good changelogs are made for humans, I strongly recommend you point people to the rendered HTML output of a nicely formatted Markdown (or other markup source language) changelog.

It’s also fine to link to a project website that formats the rendered output from the project changelog, like Ember does. You can even link to the GitHub Releases page if you generate release notes using git tags on GitHub.

Version-specific Changelog Links

What’s great about the way Keenan Brock implemented this feature compared to my original proposal is that along with other gemspec metadata, the changelog URI can be different between different versions of a gem.

This means that if your project has version-specific changelogs files, you can point people who look at version 0.1.0 on rubygems.org to a changelog-0-1-0.md file that only lists changes within this minor version.

Keeping a Changelog

What if your project doesn’t have a changelog? Or if instead you simply point people to git diffs of the commits between each version.

About a year after making the original pull request to add these changelog links to RubyGems.org, I created keepachangelog.com. Give it a read if you’re not sure what a changelog should contain or why you should keep one for your project.

It looks a little bit like this:

Concerned, you decide to immediately update this dependency, run your test suite, and deploy to production to prevent even the remote possibility of an exploitation of this vulnerability in your application.

1
2
3
4
5
bundle update nokogiri
Fetching gem metadata from https://rubygems.org/.........
(... coffee (or Mamba) time! ...)
Bundler attempted to update nokogiri but its version stayed the same
Bundle updated!

Wait, what? Why is it saying “Bundle update!” if “Bundler attempted to update nokogiri but its version stayed the same”? That’s not really what I call updated. But sure. In a situation like this I really wish that Bundler would tell me why it failed its attempt to update nokogiri.

Why won’t it bundle update nokogiri? There visibly was no error, so there must be a version requirement preventing this update I just requested. My first insinct is to check the Gemfile.lock and sift through any mention of nokogiri to see if there isn’t one requirement that’s a bit too strict and causing this issue.

But then I stop myself. Why the hell isn’t my supposed best package manager of any language ever not doing this work for me. Why am I left grepping through a Lockfile of all things like a lowly machine?

There has to be a better way, right? Well…

There is something in RubyGems that allows you to check the installed gem dependencies for a specific gem. You can ask gem dependency nokogiri and RubyGems will tell you — for each version of nokogiri — what gems depend on that specific version:

1
2
3
4
5
6
7
8
9
10
$ gem dependency nokogiri
Gem nokogiri-1.6.8.1
  mini_portile2 (~> 2.1.0)
  minitest (~> 5.8.4, development)
  racc (~> 1.4.14, development)
  rake (~> 10.5.0, development)
  rake-compiler (~> 0.9.2, development)
  rake-compiler-dock (~> 0.5.1, development)
  rdoc (~> 4.0, development)
  rexical (~> 1.0.5, development)

You might hope that perhaps Bundler implements similiar functionality that is instead Gemfile-aware. Wouldn’t that be neat? Something like:

1
2
3
4
5
6
7
8
9
bundler dependencies nokogiri
  mini_portile2 (~> 2.1.0)
  minitest (~> 5.8.4, development)
  racc (~> 1.4.14, development)
  rake (~> 10.5.0, development)
  rake-compiler (~> 0.9.2, development)
  rake-compiler-dock (~> 0.5.1, development)
  rdoc (~> 4.0, development)
  rexical (~> 1.0.5, development)

I’m sorry to say, Bundler offers no such thing. At least none that I could find in its documentation, source, issues, or pull requests.

But there’s hope. The kind Joe Mastey has created a little gem called bundler-stats which allows to get some basic statistics about your Gemfile dependencies. bundler-stats can sift through your Gemfile and figure out how many transitive dependencies each of the gems declared in your Gemfile are pulling along, which is quite useful. What I wanted however is an extension to the bundler-stats show <gemname> command which finds all gems in your Gemfile which depend on the target gem.

1
2
3
4
5
6
7
8
9
10
11
$ bundle-stats show nokogiri
bundle-stats for nokogiri

depended upon by (34) | actioncable, actionmailer, actionpack,
actionview, approvals, capybara, capybara-screenshot, chromedriver-
helper, coffee-rails, devise, devise-two-factor, draper, formtastic,
gretel, haml-rails, html2haml, inline_svg, loofah, prawn_rails, rails,
rails-controller-testing, rails-dom-testing, rails-html-sanitizer,
railties, responders, rspec-rails, sassc-rails, sprockets-rails, xpath
depends on (1)      | mini_portile2
unique to this (1)   | mini_portile2

If only I could have had the version of nokogiri required for each of those gems listed alongside them I could have easily figured out which was holding nokigiri’s update back.

…

So I added bundle-stats versions nokogiri. :-D

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
$ bundle-stats versions nokogiri
bundle-stats for nokogiri

depended upon by (34):
+------------------------------|-------------------+
| Name                         | Required Version  |
+------------------------------|-------------------+
| capybara-screenshot          | >= 1.3.3          |
| capybara                     | >= 1.3.3          |
| loofah                       | >= 1.5.9          |
| rails-html-sanitizer         | >= 1.5.9          |
| coffee-rails                 | >= 1.6            |
| devise                       | >= 1.6            |
| formtastic                   | >= 1.6            |
| google-rails                 | >= 1.6            |
| haml-rails                   | >= 1.6            |
| prawn_rails                  | >= 1.6            |
| rails                        | >= 1.6            |
| rails-controller-testing     | >= 1.6            |
| rails-dom-testing            | >= 1.6            |
| xpath                        | ~> 1.3            |
| inline_svg                   | ~> 1.6            |
| chromedriver-helper          | ~> 1.6            |
| approvals                    | ~> 1.6            |
| html2haml                    | ~> 1.6.0          |
+------------------------------|-------------------+

This tells me that haml2haml (2.0.0) is being a little overspecific with the version of nokogiri it is requiring. All the other requirements should allow nokogiri 1.8.x to be installed but this one won’t.

A quick check on RubyGems.org shows me that html2haml 2.1 and later fixed this restrictive requirement.

After checking bundle-stats versions html2haml, I don’t see a specific requirement for html2haml 2.0.0:

1
2
3
4
5
6
7
8
9
$ bundle-stats versions html2haml
bundle-stats for html2haml

depended upon by (1):
+------------------------------|-------------------+
| Name                         | Required Version  |
+------------------------------|-------------------+
| haml-rails                   | >= 1.0.1          |
+------------------------------|-------------------+

I can now be confident that running the following command will successfully update nokogiri:

1
bundle update html2haml nokogiri

This new bundle-stats versions <gemname> is not yet available in the released version of bundler-stats but it hopefully will be soon. I hope this will convince the Bundler team that this sort of feature is a must-have for a modern package manager. I honestly didn’t think I could learn all I needed to learn about Bundler to implement this as a Pull Request to Bundler but I did learn a ton about how the internals of RubyGems’ Gem::Version, Gem::Requirement, and Gem::Dependency work thanks to Joe’s work on bundler-stats.

If you’re curious about this stuff, you can take a look at the changes introduced in the Pull Request.

Update (March 15th, 2018)

Since this post was published yesterday, Joe Mastey kindly worked with me to merge the pull request and he released version 1.1.0 of bundler-stats that now includes the bundle-stats versions command so all you have to do is gem install bundler-stats and you can start using it on your Gemfiles. He even added a lovely changelog to the project.

Additionally, André Arko from Bundler reached out on Twitter to let me know that he’d accept a pull request to add this behavior to Bundler’s bundle show <gemname> command which currently prints the installation directory for a given gem. I think I’ll try to find some time before the end of the week to get started on that pull request although it’ll probably be a bit more tricky than to do this cleanly inside Bundler.

If you want to help, feel free to reach out on Twitter or to open a pull request on Bundler yourself and let me know.

Update

In Homebrew 1.5 and above, there’s a new process to upgrade your Postgres database across major versions using the brew postgresql-upgrade-database command which was recently added by Mike McQuaid.

This is a fantastic one-step improvement over the lengthy guide you’ll see below, but since this new command isn’t foolproof (it will fail if you haven’t killed all processes connected to your database) it seems like a good idea to still understand the way it works behind the scenes.

I’ve learned a cool new trick from Homebrew’s upgrade command however and you can find it in the last section of this updated post.

Accidental Homebrew Upgrades

This guide assumes that you recently ran brew upgrade postgresql and discovered to your dismay that you accidentally bumped from one major version to another: say 9.3.x to 9.4.x. Yes, that is a major version bump in PG land.

Some of the common signs of this issue are the following statements in your logs:

1
2
FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 9.5, which is not compatible with this version 9.6.

1
2
PG::InternalError: ERROR:  incompatible library "/usr/local/lib/postgresql/dict_snowball.so": version mismatch
DETAIL:  Server is version 9.5, library is version 9.6.

No need to panic. Your data should be fine. While you’ve upgraded the Postgres library, your existing databases have not been removed. They simply need to be upgraded to run with the new library.

Important Caveat for Non-Incremental Upgrades

The process I describe below will work for incremental version updates: for example 9.5 to 9.6. But it will probably not work if you jump versions: for example 9.5 to 10.0.

In order to upgrade properly you will first need to downgrade the Postgres version in Homebrew to the version directly after the one of your data directory.

How do you figure out what version your data directory uses? Ask it.

1
2
cat /usr/local/var/postgres/PG_VERSION
9.5

There we go. And what is your currently activated Postgres version in Homebrew?

1
2
$ psql --version
psql (PostgreSQL) 9.6.6

Good. If you find yourself one step further than you should be, say on 10.0 like I was. You can do the following to step back down to 9.6:

1
2
3
4
brew uninstall postgresql
brew install postgresql@9.6
brew services start postgresql@9.6
brew link postgresql@9.6 --force

Couldn’t you use this to go back to Postgres 9.5? Yes, you could. But it’s never a bad idea to stay up to date with newer versions, so why not use the opportunity to be less worried about upgrades?

Now, check the active version of Postgres with:

1
2
$ psql --version
psql (PostgreSQL) 9.6.6

Checking Versions

You can check all the versions of postgres that are installed in Homebrew with:

1
2
3
$ brew list --versions | grep postgres
postgresql 9.4.5_2 9.5.0 9.5.4_1 9.5.3
postgresql@9.6 9.6.6

In this case you can see that I don’t have Postgres 9.6 installed in the usual postgres formula, since I had to specifically install that version in order to be able to upgrade from 9.5 with brew install postgresql@9.6.

So there are 5 different versions of PostgreSQL installed on my machine in different subfolders. We can find out where those are with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$ brew info postgresql
postgresql: stable 10.1 (bottled), HEAD
Object-relational database system
https://www.postgresql.org/
Conflicts with:
  postgres-xc (because postgresql and postgres-xc install the same binaries.)
/usr/local/Cellar/postgresql/9.4.5_2 (3,030 files, 33.6MB)
  Poured from bottle on 2015-11-09 at 05:23:00
/usr/local/Cellar/postgresql/9.5.0 (3,122 files, 34.9MB)
  Poured from bottle on 2016-02-11 at 22:16:06
/usr/local/Cellar/postgresql/9.5.3 (3,142 files, 35.0MB)
  Poured from bottle on 2016-06-16 at 16:19:04
/usr/local/Cellar/postgresql/9.5.4_1 (3,147 files, 35MB)
  Poured from bottle on 2016-10-08 at 02:50:55
...

As you can see I have my old versions installed in /usr/local/Cellar/postgresql/. And what about this new postgres@9.6?

That one’s in a standalone directory:

1
2
3
4
5
6
7
$ brew info postgresql@9.6
postgresql@9.6: stable 9.6.6 (bottled) [keg-only]
Object-relational database system
https://www.postgresql.org/
/usr/local/Cellar/postgresql@9.6/9.6.6 (3,273 files, 36.8MB) *
  Poured from bottle on 2018-02-07 at 09:24:03
...

One final check to make sure we have the correct versions of the Postgres commands running:

1
2
psql --version
psql (PostgreSQL) 9.6.6

This means that the pg_upgrade binary we’ll be using is also the new one. But let’s not assume:

1
2
pg_upgrade --version
pg_upgrade (PostgreSQL) 9.6.6

Good good.

Mise en place

The directory where your actual database data is stored is different from the one where your PostgreSQL binaries are installed. Homebrew installs the data directory in /usr/local/var/postgres/ and doesn’t touch that data folder when you upgrade from one version to the next. This is a good thing because if Homebrew tried to install a brand new database (with initdb) it could squash all your existing data.

First I recommend moving your existing data to a directory with a different name:

1
mv /usr/local/var/postgres/ /usr/local/var/postgres.9.5.backup/

Now that the old data directory has been “moved”, you can safely create a brand new clean database:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
initdb /usr/local/var/postgres/
The files belonging to this database system will be owned by user "olivierlacan".
This user must also own the server process.

The database cluster will be initialized with locale "en_US.UTF-8".
The default database encoding has accordingly been set to "UTF8".
The default text search configuration will be set to "english".

Data page checksums are disabled.

creating directory /usr/local/var/postgres ... ok
creating subdirectories ... ok
selecting default max_connections ... 100
selecting default shared_buffers ... 128MB
selecting dynamic shared memory implementation ... posix
creating configuration files ... ok
creating template1 database in /usr/local/var/postgres/base/1 ... ok
initializing pg_authid ... ok
initializing dependencies ... ok
creating system views ... ok
loading system objects' descriptions ... ok
creating collations ... ok
creating conversions ... ok
creating dictionaries ... ok
setting privileges on built-in objects ... ok
creating information schema ... ok
loading PL/pgSQL server-side language ... ok
vacuuming database template1 ... ok
copying template1 to template0 ... ok
copying template1 to postgres ... ok
syncing data to disk ... ok

WARNING: enabling "trust" authentication for local connections
You can change this by editing pg_hba.conf or using the option -A, or
--auth-local and --auth-host, the next time you run initdb.

Success. You can now start the database server using:

    postgres -D /usr/local/var/postgres
or
    pg_ctl -D /usr/local/var/postgres -l logfile start

Your output will be slightly different. For one, the user won’t be olivierlacan but whatever your system user is. You can find that out easily with whoami.

Interesting to note, but if you use PostgreSQL with Rails. This means there will be no password on your development database, so you can skip the password field in database.yml or leave it *completely empty.

Shutting Things Down

First we have to make sure both database servers are not running when we do the upgrade:

1
2
pg_ctl -D /usr/local/var/postgres stop -m fast
pg_ctl -D /usr/local/var/postgres.9.5.backup stop -m fast

If you get the following message it’s possible that you have PG in launchctl which may prevent you from stopping the server:

1
pg_ctl: server does not shut down

In that case let’s remove PG from launchctl for now, you can add it back later by following the instructions given on brew info postgres:

1
2
launchctl unload -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
rm ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

Then try stopping the server again:

1
pg_ctl -D /usr/local/var/postgres stop -m fast

This would be good news:

1
2
pg_ctl: PID file "/usr/local/var/postgres/postmaster.pid" does not exist
Is server running?

If you’re using a recent version of Homebrew (as you should), then it’s likely you’re using Homebrew Services instead of launchctl to manage persistent processes like postgres. So use this instead:

1
brew services stop postgresql

While Homebrew Services should do the job of stopping postgres, it’s not guaranteed that you don’t have a server process connected to postgres and locking it’s pid (process ID) file. It’s always a good idea to check for that file which may exist at /usr/local/var/postgres/postmaster.pid. If it does, remove it with rm /usr/local/var/postgres/postmaster.pid and you’ll save yourself some surprises later on.

Upgrading

I’ve based this article on the fairly detailed pg_upgrade guide in the PostgreSQL documentation. If you have specific needs (very large data directory for example), you should consult it too. This section is also not specific to a macOS Homebrew install of Postgres since it uses the same commands you should be able to use on other operating systems like Linux.

Assuming you’re dealing with the same version numbers I’m dealing with (you probably aren’t, so change them when running this on your machine), this is what the pg_upgrade command should look like when you run it:

1
2
3
4
$ pg_upgrade -b /usr/local/Cellar/postgresql/9.5.4_1/bin/ \
             -B /usr/local/Cellar/postgresql@9.6/9.6.6/bin/ \
             -d /usr/local/var/postgres.9.5.backup/ \
             -D /usr/local/var/postgres

Lowercase flags (-b and -d) are for old binary and data directories respectively. Their uppercase counterparts are for their new equivalents.

I really dislike short form flags because they make self-descriptive discovery very difficult so here is the alternative with long-form flags:

1
2
3
4
$ pg_upgrade --old-bindir /usr/local/Cellar/postgresql/9.5.4_1/bin/ \
             --new-bindir /usr/local/Cellar/postgresql@9.6/9.6.6/bin/ \
             --old-datadir /usr/local/var/postgres.9.5.backup/ \
             --new-datadir /usr/local/var/postgres \

How nice is this?

You should see the following output immediately if the upgrade process is starting:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is a superuser                       ok
Checking for prepared transactions                          ok
Checking for reg* system OID user data types                ok
Checking for contrib/isn with bigint-passing mismatch       ok
Checking for invalid "line" user columns                    ok
Creating dump of global objects                             ok
Creating dump of database schemas
                                                            ok
Checking for presence of required libraries                 ok
Checking database user is a superuser                       ok
Checking for prepared transactions                          ok

If pg_upgrade fails after this point, you must re-initdb the
new cluster before continuing.

Performing Upgrade
------------------
Analyzing all rows in the new cluster                       ok
Freezing all rows on the new cluster                        ok
Deleting files from new pg_clog                             ok
Copying old pg_clog to new server                           ok
Setting next transaction ID and epoch for new cluster       ok
Deleting files from new pg_multixact/offsets                ok
Copying old pg_multixact/offsets to new server              ok
Deleting files from new pg_multixact/members                ok
Copying old pg_multixact/members to new server              ok
Setting next multixact ID and offset for new cluster        ok
Resetting WAL archives                                      ok
Setting frozenxid and minmxid counters in new cluster       ok
Restoring global objects in the new cluster                 ok
Adding support functions to new cluster                     ok
Restoring database schemas in the new cluster
                                                            ok
Creating newly-required TOAST tables                        ok
Removing support functions from new cluster                 ok
Copying user relation files
                                                            ok
Setting next OID for new cluster                            ok
Sync data directory to disk                                 ok
Creating script to analyze new cluster                      ok
Creating script to delete old cluster                       ok

Upgrade Complete
----------------
Optimizer statistics are not transferred by pg_upgrade so,
once you start the new server, consider running:
    analyze_new_cluster.sh

Running this script will delete the old cluster's data files:
    delete_old_cluster.sh

You’re done!

Restarting

You manually shut down PG during this upgrade so now it won’t be running unless you follow the (old) brew info postgres instructions:

1
2
ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents
launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

With Homebrew Services, the operation is even simpler:

1
2
brew services start postgresql
==> Successfully started `postgresql` (label: homebrew.mxcl.postgresql)

Once PG is running you could run the optimization script recommended by pg_upgrade. It was created in whichever directory you ran pg_upgrade in, and you can run it with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
./analyze_new_cluster.sh
This script will generate minimal optimizer statistics rapidly
so your system is usable, and then gather statistics twice more
with increasing accuracy.  When it is done, your system will
have the default level of optimizer statistics.

If you have used ALTER TABLE to modify the statistics target for
any tables, you might want to remove them and restore them after
running this script because they will delay fast statistics generation.

If you would like default statistics as quickly as possible, cancel
this script and run:
    "/usr/local/Cellar/postgresql/9.5.4_1/bin/vacuumdb" --all --analyze-only

(...)

Troubleshooting

You may encounter the following error:

1
2
3
4
5
6
7
*failure*
Consult the last few lines of "pg_upgrade_server.log" for
the probable cause of the failure.

There seems to be a postmaster servicing the new cluster.
Please shutdown that postmaster and try again.
Failure, exiting

This means you have at least one PG server running. So go back to the beginning of this section and make real sure you shut down all your servers.

You can also check this pg_upgrade_server.log file to be certain of the issue. It should be located in /usr/local/var/log/pg_upgrade_server.log but you can always use the find command to locate it:

1
find / -name pg_upgrade_server.log

When using brew postgresql-upgrade-database, this log should contain the reason the upgrade process failed as well as the actual command used, which will be very useful for you to restart the upgrade process manually.

I’ve found that running brew postgresql-upgrade-database again after an initial failed attempt usually results in an error message saying that the data was already upgraded when it’s not actually true or at least the process hasn’t fully completed.

You can see how this script works by checking its source code. It seems like it’s comparing the Homebrew-installed version to the version of the currently active Postgres database inside of the /var/postgres data directory. It references the PostgreSQL documentation upgrade article as well. The only notable difference with the instructions I’ve listed above is the use of the -j flag, which defines how many threads or processes the pg_upgrade command will use. Homebrew sets that number to Hardware::CPU.cores.to_s which would be 2, 4, 6 or more CPU cores your machine may have to handle CPU-intensive tasks like these.

However I’d recommend not doing this since you may have operations already using some CPU on your machine. My best tip is to use one less core than your total, which I learned from this excellent Thoughbot blog post on parallel RubyGem install configuration for Bundler:

1
2
3
number_of_cores=`sysctl -n hw.ncpu`
echo "$(expr $number_of_cores - 1)"
11

So here’s the final command in its full glory for all of you who skipped straight to the bottom of this post:

1
2
3
4
5
$ pg_upgrade --old-bindir /usr/local/Cellar/postgresql/9.5.4_1/bin/ \
             --new-bindir /usr/local/Cellar/postgresql@9.6/9.6.6/bin/ \
             --old-datadir /usr/local/var/postgres.9.5.backup/ \
             --new-datadir /usr/local/var/postgres \
             --jobs $(expr $(sysctl -n hw.ncpu) - 1)

Safe upgrades!

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.

The responsibility of organizing the voting, judging, travel accomodations, and ceremony has rested largely on my shoulders (with much needed assistance from Ruby Central and Code School) for the past two years after I was handed the reins of the event. I’ve also been maintaining the Rails codebase for many years now.

I’m at a point in my life where I can’t spare the time to dedicate to this project every year, but I’d be lying if I said this was my sole reason for pulling the plug.

It’s possible that someone in the community will want to keep Ruby Heroes going on in some form as several copycat events (which have no association to Ruby Heroes) have been sprouting at diverse Ruby conferences around the world in recent years. I’ve considered that myself.

But truthfully, I don’t think an award ceremony — however friendly and informal — is an appropriate solution to try and foster a culture of appreciation in the Ruby community anymore.

I worry that despite the initial focus of Ruby Heroes having been to shine a light on underappreciated members of the community, it has invariably become a place to annoint respected members of the community who — despite being quite worthy of accolades — don’t really need them. I say this knowing full well that some well-known recipients have been deeply touched by receiving a Ruby Hero Award in the past.

Then there’s the contentious issue of praise and rewards. Even a cursory reading of Alfie Kohn’s seminal book Punished by Rewards can shake the conviction that good intentions excuse all unintended side-effects of handing people awards. To summarize Kohn’s argument, it’s very likely that rewards motivate people for the wrong reasons, demotivate those who didn’t need awards to be motivated in the first place, and generally tend to turn something enjoyable into a chore because only chores must prompt compensation with a reward.

While I believe that Ruby Heroes has benefited some of its recipients personally and professionally over the years, I can’t shake the feeling that it’s also had a much less visible negative impact on their and other people’s long term motivation in the long run. I could be wrong.

Although they have a different focus, initiatives like Ruby Friends and SayThanks.io are giving Rubyists a way to appreciate each other and the community members they look up to. I welcome all initiatives from the open source and Ruby communities to spread thankfulness, appreciation, and gratitude.

One of the best perks of the job has been to read the amazingly kind comments people sent throughout the years about their Ruby Heroes nominees. I don’t know if these kind words are best kept private or public. But I know how something so simple as a grateful tweet or email can have a similar deep lasting impact on the recipients.

There are many ways to appreciate the people who inspire you and make your community better. You can thank them, hug them or you can help them by supporting the efforts they hold dear. RubyGems.org recently made it possible to find reverse dependencies for gems. Think about the human dependency graph of our community. Who depends on whom and vice versa?

Libraries.io offers a fantastic tool called “Improve the Bus Factor” which lists the most highly dependended upon libraries with the fewest maintainers and contributors. If that’s not a call to action, I don’t know what is.

PS: Thanks to everyone who has supported the mission of Ruby Heroes throughout the years in spite of its failings. I’ve never been more proud of the Ruby community now that it’s out of the brightest limelight, and I can’t wait to see all the amazing people and projects that will make it up in the years to come.

At Ruby Kaigi 2016, Koichi Sasada — designer of the current Ruby virtual machine and garbage collector — presented¹ his proposal for a new concurrency model in Ruby 3.

While Ruby has a thread system to allow for concurrency, MRI doesn’t allow parallel execution of Ruby code. Koichi looked at the various challenges of running Ruby in parallel including object mutation, race conditions, and synchronization across Threads. The result was a proposal for a new concurrent and parallel mechanism called Guilds.

Concurrency Goals

If like me you’re not a computer science graduate, or if concurrency just tends to hurt your brain, you can read this clear explanation of the differences between concurrency and parallelism.

The stated goals for Guilds in Ruby 3 are to retain compatibility with Ruby 2, allow for parallelism, reconsider global locks that prevent parallel execution, try to allow fast object sharing, and provide special objects to share mutable objects.

Concurrency in Ruby today is difficult because programmers have to manually ensure that Threads don’t create race conditions. Common ways around this issue involve introducing locks, like Ruby’s Thread::Mutex, which somewhat defeat the initial purpose of parallelism. Locks tend to slow down programs, and improperly placed locks can even make concurrent programs run slower than synchronous equivalents.

How Guilds Work

Note: With Koichi’s permission, I’ve reproduced some illustrations from his proposal since they’re helpful for understanding the concepts.

Guilds are implemented in terms of the existing Thread and Fiber classes. While Threads allow for concurrent execution of code scheduled by the operating system scheduler on your behalf, Fibers allow for cooperative concurrency with execution scheduling that can be manually controlled.

Guilds are composed of at least one Thread which in turn has at least one Fiber. Threads from different Guilds can run in parallel while Threads in the same Guild can’t. Objects from one Guild cannot read or write to objects from another Guild.

Threads that belong to the same Guild can’t execute in parallel since there’s a GGL (Giant Guild Lock) ensuring that each thread within a Guild executes one after another. However, Threads from different Guilds can execute in parallel.

You can think of a Ruby 2.x program as having a single Guild.

Communication Between Guilds

An object from one Guild will not be able to read or write to a mutable object from a different Guild. Preventing mutation allows Guilds to operate concurrently without running the risk of both accessing and modifying the same objects.

However, Guilds can communicate with each other using the Guild::Channel interface which allows for the copying or moving of objects across the channel to another Guild.

The Guild::Channel’s transfer(object) method sends a deep copy of the object to a destination Guild.

It’s also possible to completely move an object from one Guild to another using Guild::Channel’s transfer_membership(object).

Once an object’s membership has been transferred to a new Guild, it is no longer accessible from its original Guild, and any attempt to access the object will raise an error.

While Guilds can’t share mutable objects without previously copying or transferring to one another, it’s important to note that immutable objects can be shared (read) across Guilds as long as they’re “deeply frozen”, meaning every object they reference is also immutable.

Here’s an example to distinguish mutable from immutable objects:

1
2
3
# While Numeric types like Integers are immutable by
# default, Hash instances aren't.
mutable = [1, { "key" => "value" }, 3].freeze

1
2
3
4
5
6
7
# But if you freeze String or Hash instances and the
# Array instances that reference them, then you have
# a "deeply frozen" immutable object.
immutable = [
  "bar".freeze,
  { "key" => "value".freeze }.freeze
].freeze

Usage Example

During his talk, Koichi Sasada gave a few succinct examples of how Guilds could work. I’d like to reproduce the simplest one that applies Guilds to computing Fibonacci in parallel. The example below has been modified slightly for clarity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
def fibonacci(n)
  return n if n <= 1
  fibonacci( n - 1 ) + fibonacci( n - 2 )
end

guild_fibonacci = Guild.new(script: %q{
  channel = Guild.default_channel

  while(n, return_channel = channel.receive)
    return_channel.transfer( fibonacci(n) )
  end
})

channel = Guild::Channel.new \
  guild_fibonacci.transfer([3, channel])

puts channel.receive

Advantages of Guilds over Threads

With Threads, it’s difficult to figure out which objects are shared mutable objects. Guilds prevent their use altogether and instead makes sharing immutable objects much easier. Koichi has planned for “special data structures” to share mutable objects with Guilds. These structures would automatically isolate risky mutable code.

There is, however, a trade-off, since communication between Guilds is much more tedious than between Threads.

Performance

It’s my understanding that the current C implementation of Guilds is roughly 400 lines of code. While the source isn’t yet available, Koichi hinted at the performance benefits of Guilds by comparing a single-guild execution of the fibonacci example with a multi-guild one.

On a dual core Linux virtual machine running within Windows 7, Koichi observed the following results:

It may not be representative of real-world improvement in most Ruby applications, but I can’t wait to see the impact of Guilds on RubyBench.

Conclusions

The Guild concept is an exciting way to introduce easier mutation-safe concurrency workflows to Ruby. I can’t wait for Koichi Sasada and the Ruby core team to share more about this proposal in the future.

I do have minor concerns about the naming of the object copy and move methods for Guild::Channel. transfer(object) seems to imply an exchange, but it merely results in a deep copy of the object. I believe transfer_copy(object) or simply copy(object) would be less confusing. And transfer_membership(object), the move/transfer method, could simply be named channel.transfer(object). Thankfully, it seems that the method names aren’t set in stone.

I’d encourage the Ruby core team to release this new feature under an opt-in experimental flag so that the Ruby community can participate in testing. Hopefully, this would allow us to have this feature available before 2020 — the expected release date of Ruby 3.0. Guilds will have a positive impact on Ruby’s reputation as a concurrent-friendly language. It would be welcome soon, warts and all.

Although the circumstances are more rushed than I would have hoped, I’m starting a weekly Ruby news podcast called Ruby Facets. The first episode is already available and I’m using Patreon to fund the ongoing production of the show.

If you were a Ruby5 listener in the past, Ruby Facets may sound familiar to you. There’s a reason for that. Ruby5 is no more. After 7 years, 645 episodes, 69 hosts, and lots of fun, Code School — who’s been producing and funding the show for about 3 years — decided it was time to move on.

It’s not really a judgement of Ruby5 as a show, Code School simply stopped producing all the five-minute podcasts based on Ruby5 — FiveJS and iOS Bytes too. I have very mixed feelings about this decision but ultimately it’s up to us as community members to decide what we’d like to contribute.

I think I still have something to contribute to the Ruby community in the form a news podcast. Ruby Facets will not try to be exactly everything that Ruby5 was. For one I don’t intend on working with co-hosts for now, simply because the logistics of producing the show need to be as simple as possible considering I’m trying to fund the show without sponsors.

If there’s one thing I gathered from working with Gregg, Nate, Carlos, and many others on Ruby5 is that quality and curation matter. Ruby5 ran about 5 minutes with approximately 5 news stories which is a pretty dense information to airtime ratio compared to most podcasts. The show valued the listener’s time and had a clear purpose: keeping people up-to-date with community news.

I learned a lot from the sound quality we thrived for on Ruby5. There are sadly still plenty of podcasters who don’t recognize that if copywriting and proper grammar are not just a nice-to-have on a blog, then audio quality isn’t just a nice-to-have either on a podcast. Both are a reflection of attention to details and respect for your audience.

There’s another aspect I want to infuse Ruby Facets with as much as possible: a sense of community. Although it will be difficult to achieve with a single host, I’m going to try to synthesize the good and exciting things I see happening in the Ruby community. That will require discipline on my part since the show will be biased by my own point of view for now. Thankfully there’s all of you out there with your own opinions and ideas and exciting projects that the whole community should hear about.

If this vision for the show excites you too, you can become a patron of Ruby Facets on Patreon. Monthly donations range from $1 to $5 and I’m very interested to hear your thoughts about the show on Twitter at @rubyfacets. Instead of hoarding news until the show is released each week I plan to tweet and retweet links to stories during the week as I gather them.

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.

I used to wear glasses with a very strong prescription. The sidebar font size in Sublime drove me nuts because it’s one of those things so clearly created by someone who has excellent vision — or someone who just doesn’t know what’s good for them. Squinting at a screen is good for no one.

Last year I had LASIK. No more glasses. Near “perfect” vision. Still, the Sublime Text sidebar font size gives me headaches. On this 9th day following the anniversary of my bionic eyes, let’s fix this damn sidebar for good.

PackageResourceViewer

This step assumes you have Package Control installed. If you don’t, go do it, trust me, you’re missing on a world of Sublime goodness.

It appears that the files we need to modify (at least in Sublime 3) are now zipped and not as easy to edit as they were in Sublime 2. If you’re still on Sublime 2 the file names should be the same and you probably won’t need this step.

On Sublime 3, run Shift + Command/Control + P. Select Package Control: Install Package, then type PackageResourceViewer and press Enter to install it.

Now that it’s installed, you can summon PackageResourceViewer with the prv command inside of the Shift + Command/Control + P prompt.

Open Resource

Let’s open the resource we need to modify in order to fix this damn sidebar. First Shift + Command/Control + P, then type prv open and Enter.

You should see a list of resources. At this point your current theme name is going to matter a lot. If you’re using the default theme (you animal!) you can just type Default.sublime-theme and Enter to modify that. If you’re anything like me, you have a roster of different themes that you rotate through. I use the Themr package to list and switch themes, so before remembering which theme I was currently using I had to check Themr’s List themes command. That said one quick scroll through your user preferences (Command/Control + .) and you should be able to figure out the name of the theme you’re using.

When you know for sure which theme you’re using, type its name in the prv open listing and it should filter it down to a few results. You’re looking for a .sublime-theme file. I’m using Sodarized Dark. So first I had to open the Theme - Sodarized directory, then select the Sodarized Dark.sublime-theme file.

If you pick the wrong file, the final step will have no immediate effect so it’ll be easy to come back to this one and try a different file.

Modifying the Theme

We’re almost done! Wooh! Use your trusty old Command + F to find the sidebar_label property. This is what defines the style for the text label that displays file and directory names in the sidebar.

To start adjusting the font size you’ll need to add a new property called "font.size".

Before I changed it, my Sodarized Dark sidebar_label settings looked like this:

1
2
3
4
5
6
{
    "class": "sidebar_label",
    "color": [52, 106, 127],
    "shadow_color": [0, 0, 0],
    "shadow_offset": [0, -1]
}

After, they looked like this:

1
2
3
4
5
6
7
{
    "class": "sidebar_label",
    "color": [52, 106, 127],
    "shadow_color": [0, 0, 0],
    "shadow_offset": [0, -1],
    "font.size": 16
}

Don’t forget to add a comma (,) at the end of the previous property’s line (shadow_offset in this case) otherwise you’ll cause a syntax error.

Sweating the Details

I recommend playing with the font.size value. I settled on 16 but only after messing with the sidebar_tree property’s row_padding values that determine the padding (spacing) within each sidebar row.

I also found that changing them from their default value of [8, 3] to [8, 5] made the sidebar rows much easier to read.

I’d recommend making a backup of the original values. Otherwise you can always remove the Theme package you were modifying and re-install it from Package Control. That should restore the default theme settings.

My sidebar before:

My sidebar after:

It may not look like much, but in the context of a larger screen, it matters and my eyes thank me for spending the time to finally address this issue.

Conclusions

This post was drawn from personal frustration and it’s very much an expansion of this excellent StackOverflow response. I have to admit that it’s a bit baffling how difficult this ordeal was to accomplish such a basic change that would surely benefit many Sublime Text users. If there’s a much simpler way to achieve this (using a simple Package perhaps) then let me know and I’ll be glad to shorten this.

In the meantime, remember that it’s important to take some time to chip away at the rough edges of your tools every day. You don’t need to switch editors because something isn’t perfect in the one you’re using. You can often find solutions that don’t involve uppending your entire workflow for a few weeks.

That said, there should be a breaking point. I could have switched to Atom for less, and I have. I just haven’t found the productivity equilibrium to satisfy me in another editor yet. That doesn’t mean it won’t happen.

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.

It’s been over a year since I wrote my initial “Proposal for a better Ruby Hash#include?” and I’m so happy to announce that since Tuesday November 10, 2015, Hash comparison methods have been committed to MRI’s trunk branch by the fabulous Nobuyoshi Nakada.

This means the following Hash comparison methods will be available in Ruby 2.3 when it’s released this coming Christmas. In the meantime you can install Ruby 2.3.0-preview1 which was released today and already includes this new feature.

Comparing Hashes

What is hash comparison? This may be hard to visualize, so here’s a short example:

1
2
hash_one = { a: 1 }
hash_two = { a: 1, b: 2 }

It’s clear just by looking at hash_two that it includes the same single key and value as hash_one plus one extra key and value. So how do you check that with Ruby? Intuitively you may try the Hash#include? method, right? Let’s see.

1
2
3
# Ruby MRI 2.2 and earlier
{ a: 1, b: 2 }.include?({ a: 1 })
=> false

Hmmm. Strange, no? Well that’s because Hash#include? doesn’t compare hashes, it only looks at the keys. Worse, it will only work properly with keys as arguments. So in Ruby 2.2 and earlier, the only thing you can do is check that a hash includes the same key, like this:

1
2
3
# Ruby MRI 2.2 and earlier
{ a: 1, b: 2 }.include?(:a)
=> true

This is because Hash#include? is in fact a method alias for Hash#has_key?.

This is surprising behavior to say the least, and some Ruby libraries like RSpec implement their own Hash inclusion logic to circumvent the strange behavior of Hash#include?. As you’d expect, RSpec’s include matcher checks hashes for both key and value matching. So you can write:

1
2
# RSpec
expect({ a: 1, b: 2 }).to include({ a: 1 })

Hash Comparison Methods

My original feature proposal suggested introducing an new Hash#contain? method, but the semantics didn’t work well enough for the Ruby core developers. Matz himself said the following in the November developer meeting:

Hash#contain? has [a] slight ambiguity problem. I’d vote for adding >=, along with <=.

At first I was a little taken aback by Matz’s proposal, but Erik Michaels-Ober pointed out that I should be happy my little method proposal was becoming an operator on Hashes. And now I see, Matz and Erik were right, look how great this is:

1
2
3
# Ruby MRI 2.3.0 (trunk)
{ a: 1, b: 2 } >= { a: 1 }
=> true

For the less mathy people (like me), this may take a second to wrap your head around. I find it easier to say the operator out loud:

“Is this hash greater than or equal to this other hash?”.

A hash that contains another smaller hash is greater, so this returns true. A hash that contains the same hash is equal, so this returns true.

Here are a few more examples provided by Akira Tanaka:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Ruby MRI 2.3.0 (trunk)
{ a: 1 } <= { a: 1 } = true
{ a: 1 } <= { a: 2 } = false
{ a: 2 } <= { a: 1 } = false
{ a: 2 } <= { a: 2 } = true
{ a: 1 } >= { a: 1 } = true
{ a: 1 } >= { a: 2 } = false
{ a: 2 } >= { a: 1 } = false
{ a: 2 } >= { a: 2 } = true
{ a: 1 } <  { a: 1 } = false
{ a: 1 } <  { a: 2 } = false
{ a: 2 } <  { a: 1 } = false
{ a: 2 } <  { a: 2 } = false
{ a: 1 } >  { a: 1 } = false
{ a: 1 } >  { a: 2 } = false
{ a: 2 } >  { a: 1 } = false
{ a: 2 } >  { a: 2 } = false
{ a: 1 } == { a: 1 } = true
{ a: 1 } == { a: 2 } = false

Look at how consistent this is. You can now compare hashes exactly the same way you would compare integers.

I can’t wait for Ruby 2.3.

Does it mean Comparable is now included in Hash?

No.

The methods added to Hash are as follows:

• Hash#> — this hash instance includes the argument hash
• Hash#>= — this hash instance includes or is the same as the argument hash
• Hash#< — this hash instance is included in the argument hash
• Hash<= - this hash instance is included or the same as the argument hash

Conspicuously absent is the <=> method used by the Comparable module to sort objects. What this means is that these new methods will not interfere with your existing calls to Hash#sort.

You should pre-order a copy on Amazon while it’s still 43% off ($25.70 instead of $44.99).

After five years, Ruby is still a joy for me to use every single day. It baffles me that people refrain from using it because their friend’s uncle’s sister’s brother’s mother’s friend told them “it doesn’t scale”. You know what scales incredibly well with Ruby? The code. Refactoring code, expanding it, breaking it into parts that communicate with each other like a living organism would. Most of what you do with software is not scaling, it’s changing the code.

It’s not just Ruby, the tool, that I cherish. It’s the people of Ruby. Its creators, maintainers, and the people who sustain its community by inviting more people to it. Often, I see people making technological choices based solely on the merits of the tools. They forget to care about whether the makers of the tools are friendly or helpful human beings. But tools are made by people, and people are flawed. The flaws of their tools reflect their own flaws. Put differently, if people who dislike other people make tools, then their tools will tend to disregard people or even treat them poorly, as a second thought.

I don’t think I have to give you examples of people-unfriendly technology. There’s still far too much of it around. I believe Ruby is a beacon in a sea of tools designed to achieve an end at whatever human cost. It’s not the only beacon, but it’s the one I chose, and I’m still very happy with it.

I’ve managed to scale my professional life with Ruby. We run a business with 2 Million users using mostly Ruby and yet we don’t wake up in the middle of the night because Ruby stopped scaling. We spend far more time stressing out about operations, support, building course content, designing the best software we can for our users, and communicating with each other.

I wish the kinds of programming joys I experience daily to everyone who wants to learn how to build good, sustainable, satisfying software that focuses on helping human beings learn more and build better tools. I think Head First Ruby is a good place to start.

PS: Amazon doesn’t offer the ebook version of this book. You can buy the early release ebook version if you want to start reading today. It will be updated once the book is published.

The main reason was that wanted to keep a slug history in order to avoid 404 File Not Found errors when users decide to change an article title. I have to be able to guarantee that you will find a piece of documentation regardless of how many time its title has changed in the past.

Before

This is how slugs were generated originally in the Article model:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# app/models/article.rb
class Article < ActiveRecord::Base

  # ...

  before_validation :generate_slug

  # ...

  validates :slug, uniqueness: true, presence: true

  # ...

  def to_param
    slug
  end

  # ...

  private

  def generate_slug
    if self.slug.present? && self.slug == title.parameterize
      self.slug
    else
      self.slug = title.parameterize
    end
  end
end

And this is how they were used in the controller:

1
2
3
4
5
6
7
8
9
10
11
# app/controllers/articles_controller.rb
class ArticlesController < ApplicationController
  respond_to :html, :json

  # ...

  def show
    @article = Article.find_by(slug: params[:id]) || Article.find(params[:id])
    respond_with @article
  end
end

One important note here about find_by. Unlike the regular ActiveRecord find, find_by does not raise a RecordNotFound exception when it finds no matches. Instead it returns nil which is falsey. This is why it comes before the find call, which was only present as a legacy concern to allow people to access /articles/33 instead of using Article 33’s slug.

After

After installing FriendlyId and creating the friendly_id_slugs table, I replaced the code above with this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# app/models/article.rb

class Article < ActiveRecord::Base
  include Dateable
  extend ActionView::Helpers::DateHelper
  extend FriendlyId

  friendly_id :title, use: [:slugged, :history]

  def should_generate_new_friendly_id?
    !has_friendly_id_slug || title_changed?
  end

  def has_friendly_id_slug?
    slugs.where(slug: slug).exists?
  end
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# app/controllers/articles_controller.rb
class ArticlesController < ApplicationController
  respond_to :html, :json

  # ...

  def show
    @article = Article.friendly.find(params[:id])
    respond_with_article_or_redirect
  end

  # ...

  private

  def respond_with_article_or_redirect
    # If an old id or a numeric id was used to find the record, then
    # the request path will not match the post_path, and we should do
    # a 301 redirect that uses the current friendly id.
    if request.path != article_path(@article)
      return redirect_to @article, status: :moved_permanently
    else
      return respond_with @article
    end
  end
end

The useful method here is has_friendly_id_slug? because it allows me to check whether an article has a slug that was generated by FriendlyId or by my old ad-hoc system.

FriendlyId creates a simple has_many association between the model and FriendlyId::Slug. I could have used friendly_id (the dynamic reader method) because the default database column name for the locally-stored (on the articles table instead of the friendly_id_slugs table) slug is… slug. That’s configurable of course, but I know for a fact that the column name I had used with my ad-hoc system was slug so there’s no point in relying on FriendlyId to figure out the actual column name for me.

Why bother?

So anyway, say we have an article titled “Banana”. That article’s slug column should already be set to banana (per my ad-hoc slug system) but a freshly installed FriendlyId should mean that there is not friendly_id_slugs record for banana. Thanks to has_friendly_id_slug?, we can check.

And thanks to that check, we can decide to easily migrate all the cached slugs (i.e. on the articles table) to FriendlyId. All it takes is:

1
Article.all.each(&:save!)

Why bother? Because if we’re using FriendlyId’s History module, we need its friendly_id_slugs table to contain the original slug. Without doing this, the first slug stored in FriendlyId would be a future one (when an article’s title is eventually modified) and not the current one stored inside of the articles.slug column.

1
2
3
4
5
6
a = Article.friendly.find("banana")
a.title = "Pamplemousse"
a.save!

a.friendly.find("banana")
=> #<Article:0x0000010b6913b8

Everybody’s happy and nobody bumps into 404s! The end.

PS: Thanks to Normal Clarke for the tip that helped me find this solution.

1
2
3
4
5
class HallMonitor
  def initialize(user: nil)
    @user = user
  end
end

As you can see, I also decided to make the user keyword argument optional by making it default to nil.

Later while pairing and refactoring the implementation of the class and the associated specs, I forgot about my fancy keyword argument and simply wrote the following:

1
HallMonitor.new(user)

This raised the following error:

1
ArgumentError: wrong number of arguments (1 for 0)

I was confused for a second. I hesitated, then said “it makes no sense” out loud because I remembered making the user argument optional. Of course I had misread the exception as “wrong number of arguments (0 for 1)”, which it wasn’t.

Then I went back to the class, looked up the method definitation and went “aaaahhh!”.

But here, Ruby could have been far more helpful to me. It made sense before we had keyword arguments for Ruby to respond with an exception that would just compare the number of provided arguments against the number of required arguments. Nowadays we have keyword arguments, Ruby can tell us exactly what argument is missing and what its name is (if we use keyword arguments of course), so why not throw this exception instead:

1
ArgumentError: wrong number of arguments (1 for 0), keyword arguments: [user: nil]

This kind of simple error feedback improvements, similar to one proposed by Richard Schneeman earlier this year would probably save a Rubyists time debugging simple mistakes. And that’s bound to make them happier, isn’t it?

If you agree or disagree, let me know on Twitter or by email. I’ll submit a feature suggestion to bugs.ruby-lang.org if nobody objects for a sensible reason.

Over time, the only reliable system I’ve developed to combat it is something I called the “ego time machine”.

Once in a while, get lost in your own brain and try to remember a time when you knew less about the topic you find yourself focused on right now.

Sometimes it’s almost impossible not to feel like a fraud. You see any evidence to the contrary as a sweet lie hiding an awful awful truth.

The exercise I describe above is useful because it comes from within. It’s not external validation you can be tempted to brush off as a kind compliment. It helps you take a step back. It equips you a thought machine that will can hopefully help you to chip away at your own feelings of inadequacy.

• 5 years ago basic Object-oriented programming baffled me.
• 4 years ago I thought I would never understand Ruby on Rails.
• 3 years ago caching seemed like it was too much work.
• 2 months ago I was still afraid to look at C code.
• 1 month ago I didn’t know how databases search for records.

Looking at it this way, it’s impossible to deny the progress I’ve made and how far I’ve come.

Progress in knowledge acquisition is often hard to measure, hard to sense internally. It’s common for the people generalized as “knowledge wokers” not to realize how much they know. We often worry about whether we know enough, instead of worrying about whether we’re good at learning more. The fact that there are entire portions of my daily workload that contain activities which would have baffled me just a few years ago is immensely useful to combat the lingering sense that I’m not pulling my own weight.

In a great post called Impostor Syndrome Jason Freedman describes a ritual he follows when he fells out of his element:

I actually have this little tradition I do personally when I’m most stressed out and my body feels weak – I have this strange craving for McDonald’s. It happens every time. And I don’t really eat McDonald’s any other time in my life except for when I’m really feeling stressed. So now I have this thing whenever I’m really feeling pushed a bit too hard, I head straight to McDonald’s and have my little ceremony with my hamburger, chicken mcnuggets and fries. And I think back to all the times I have sat in this exact same seat, eating this exact same thing, feeling this exact same way. It helps me, in the moment, gain that temporal perspective that allows me to remember that this too shall pass.

This is the Ego Time Machine at its best. It reconnects you to your past accomplishments in a way that makes it near impossible for your to willfully ignore them. It forces you to see that there’s a good chance your fear and doubt are not rational. They’re part of the cycle. It gets better.

You should upgrade to one of the maintenance releases described in the link above, but that’s assuming you can.

A lot of people don’t know how to do that. A lot of people are using the git version that ships with Apple’s OS X or their operating system of choice. I can’t help you if you use Windows or Linux but head over to the Downloads section of the official git website for help.

Now if you use OS X, and if you use git regurlarly like many people who build websites and software, you now may understand why people like me recommend against using the software packages that are bundled with operating systems like OS X:

• The versions are often very old.
• It’s either hard or impossible to upgrade them without the operating system vendor.
• Operating sytem security updates don’t always update these packages, or at least not promptly.

git your own

First step to controlling your development software, install Homebrew. It’s a package manager. It works similarly to the App Store — but on the command line.

So first open the Terminal app. Command + Space to open Spotlight and just type Terminal if you don’t know where it is. You should see something like this:

Now I’m curious if you already have Homebrew installed. We can be sure by using the which command like this:

1
2
which brew
/usr/local/bin/brew

If you don’t see /usr/local/bin/brew displayed when you press Enter after entering the command, you don’t have Homebrew installed. So let’s do that.

WARNING: I’m about to tell you to do something dangerous. Downloading and executing an unknown and potentially nefarious script whose source code you’ve never read. You should not do this willy nilly. The only reason I ask you to trust me is that I trust this specific script. It’s written in Ruby. I’ve read it. And I’m mildly confident no one has hacked my blog to replace the link with a nefarious one.

In any case, you can find the source code of the script right here: https://raw.githubusercontent.com/Homebrew/install/master/install

Paste the following command in your Terminal window and press Enter:

1
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once the installation is over, I recommend you run the following command:

1
2
brew doctor
Your system is ready to brew.

Homebrew can’t heal itself but it can diagnose anything on your system that may hinder its functioning. Usually that will involve installing a version of Xcode which you can now simply find on the App Store.

Whenever brew doctor answers with Your system is ready to brew., you’re ready to install git. Just run:

1
brew install git

Once you do, I suggest you quit (Command + ‘Q’) the Terminal app. I don’t say this because restarting the app magically makes everything works right. It’s because we installed a new binary and it may not be available on the load path immediately. You can check that by running:

1
which -a git

This command looks for all available binaries matching the name git anywhere on your load path ($PATH). Whereas which git will only tell you the one which will be used to answer calls to git. The first directory path in the list will be the one used. If you see /usr/local/bin/git at the top, congratulations, you’ve installed your own git. You can check the version of the git you installed with git --version. It should be higher than 2.2.1.

If which git yields /usr/bin/git then the Apple-installed git is still taking precedence over the one we just installed with Homebrew. That’s completely normal and okay. It just means we have a wee bit of work left to do.

Let’s talk about your $PATH. The reason why you’re seeing the Apple-installed version respond first is because of that loading path. I’ve written a long piece for A List Apart on this topic if you care to learn more but if you want to get it over with quick, let’s do this:

1
echo $PATH | tr ":" "\n"

This should list all the paths in your load path in order of precedence. For you, I can bet that /usr/local/bin is showing up below /usr/bin.

All we need to do is prepend the /usr/local/bin path in the load order.

First run these commands:

1
2
cd
ls -a | grep bash

The first command takes you to your home directory wherever you are. It’s a neat trick to quickly go home without having to type anything else.

The second command lists all directory contents including dotfiles (-a) and then filters the list of returned files and directories to only show the ones which have the word bash inside them.

Mine only outputs:

1
2
.bash_history
.bash_profile

If you have a .bashrc file it’s likely you created it following someone’s advice on the internet. Check to make sure it doesn’t contain path modifications:

1
cat .bashrc

If you don’t see anything that ressembles PATH= then you’re fine, otherwise I recommend you put all your path modifications in the same place. I put mine in .bash_profile. If you want to read more about configuration files, I recommend this and that StackOverflow discussions.

Here’s how to modify your path to prepend the /usr/local/bin directory:

1
export PATH="/usr/local/bin:$PATH"

Make sure to put that near the top of your .bash_profile and annotate it with a note about its purpose so you can understand it when you find it later. I often leave links to the resources I’ve used, like this blog post, so I can understand why I modified my configuration later.

You can’t judge a book by its cover

You’ve surely had this trope dogmatically thrown at you at some point. Perhaps by someone fond of prepackaged thinking and unsolicited advice. It may have had uses as a tool to protect people against easy judgement, but when generalized in its popular form, it’s thoughtless.

I’m going to make a daring assumption: you and I agree that design usually tends to improve things. I know, a certain Jony has recently proved to us that designers who achieve a little bit too much power can in fact make things worse for a lot of people. But in general, design is a system of thinking with the purpose of achieving something not only beautiful but functional and friendly to its user as well.

If we do agree on this definition, here’s what a book’s cover tells me about what’s inside. It tells me that someone involved in the creation of the book cared about its initial perception. The perception that someone with no prior knowledge of the book, its author, its publisher, its subject — anything — would have about the book.

Caring about a the cover takes humility and empathy. Despite their involvement bias, whoever does care about the cover realizes that there may be humans on earth who do not know why this book matters. Why they should read it.

There are some essential elements to a cover. Just imagine for a second an utterly blank cover: a pure white piece of thick paper. What does it tell you about the book? It tells you that someone, perhaps the author, believes that it’s unnecessary for the book to have any external means of identification. This is an extreme example. It’s always easier to reveal the cracks in an argument when you push its to its logical limit.

Now let’s take a beautiful cover. It has everything. The title and the author’s name are carefully printed with an elegant typeface and located unambiguously on the front and the spine. There’s an interesting illustration that attracts attention in a bookstore regardless of the prospective reader’s artistic preference. If the title doesn’t make the subject of the book self-evident, perhaps there’s a short subtitle which will secure the interest of someone whose attention was captured from afar but perhaps wasn’t exactly sure of the subject matter. If there are pull-quotes in the back, they’re not ridiculously superlative but they simply ignite more curiosity if they originate from people who the passerby respects and whose opinion they trusts.

Let’s stop here. Wouldn’t you judge this cover significantly differently that you would the blank one? Aside from the fact that a blank cover would admittedly make a book stand out, the odds of you not even being able to judge the blank cover because you won’t see it are great.

It doesn’t take bad design to make good design stand out. It helps, of course. In a sea of blue icons, a red one stands out. It’s a statement. You will judge that statement. It will give you information, however tenuous, about the application behind the icon.

A few years ago I was looking for an accountant. Despite being the son of an accountant, I know next to nothing about the topic. Especially because what little I knew related to accounting in France, not in the U.S. From experience, I only had a few keywords to help me in my search. I knew I was looking for a CPA, Certified Public Accountant. After unsuccessfully asking a few friends for a recommendation, my patience ran short and I decided to take two approaches: Google and Yelp.

I assumed that Google would be littered with paid ads and SEO-gamed results (it was) which would limit my ability to discern good choices from bad ones considering I basically had no criteria to compare a good from a bad CPA. Moreover I didn’t expect an accountant’s website to help me judge whether they were good at what they do. Unlike web designers, their job isn’t to maintain an attractive website.

My one hope laid in the book’s cover. Devoid of an ability to judge the substance of something, appearances turn into a powerful signal. So I loaded up a dozen of CPA websites. I filtered the ones with the highest ratings on Yelp and the ones that appeared to be from my local area in Google. I wanted to meet this person. I needed to be able to trust them.

Immediately I saw a barage of stock photography. Some woefully inadequate for accounting matter. I spotted some obvious and unimaginative WordPress themes which were poorly adapted to the task of conveying trustworthiness and experience.

Then something strange happened. I found a beautiful website. Clear navigation focused on what I wanted to know: who this person is, what they do, why it matters, and why they should be trusted.

More importantly, there was a sense of taste pervading from the site. You could question the choice of style, but it was unquestionably applied by someone who knew what they were doing. It didn’t matter to me whether this CPA built the site themselves or paid someone to do it. All that mattered was that they cared. That told me a lot. The tone of the website’s copy was concise, it was fresh. It made me want to trust them because it wasn’t boilerplate and it wasn’t stuffy.

Now it’s possible that this website may have had a different effect on someone older than me or someone from a less web-savvy background who doesn’t respond to these cues because they have no special appreciation for good typography, good copy, good content design. But I believe an effect nonetheless. Even ill-equipped to measure professionalism, people can smell it. They can feel it. I know I did.

After leaving a message using the contact form conveniently accessible on the home page of the site, I received a phone call from the CPA herself. She matched her cover perfectly. She was warm, professional, sharp and before calling me she even did her homework by looking me up based on the email address I purposefully used on the contact form. She knocked it out of the park.

This superficial impression was later confirmed when I met her and the rest of her team. I judged a book by its cover, and it was a damn good book. This is not the first time it has worked out well for me: books, music, restaurants, programming language communities, and even people.

It’s true that I’ve discovered bad books with great covers, but unless I’m letting confirmation bias get the best of me, I’ve had more lucky strikes than bad apples.

PS: Skeptics of this conclusion may delight in the fact that for whatever reason, a few after I started working with the CPA I mention in this post, they entirely ghosted me. I’m not sure if they went under, had an influx of much more profitable clients, a huge technical issue, or if something else happened. So my little anecdote took a hit. While I know some beautiful covers might hide nastiness, that doesn’t completely change my point of view on the signal that a well-crafted one sends.

Katie is a programmer and a damn good one. Yet we probably only write code together 15% of the time. Most of the time we talk about code. We talk about interfaces. How names feel. How things fit together. We get excited about deleting huge chunks of code. We pause while I try to paraphrase something brilliant she just said because the world needs to know and I must tweet it now.

Morgan is bothered by not understanding something. When she wants to understand, at first I think: “Sure, I know how that works. We can take a short detour so I can explain that.”. Then I realize: “Shit, actually I have no idea how that works. How the fuck have I never bothered to look into this?”. So we pair. I can use the accumulated system knowledge I have and, with her, come to a satisfying solution faster. Perhaps because she doesn’t know yet where and what to look for. Yet, without her I would have never looked. I owe her that fresh perspective. This renewed attention to details that you often lose when so many things need fixing.

Joel is a linguistics nerd like me so together we defy the adage that programmers suck at naming things. That said, we sure talk about naming things a lot. When we pair, I spend a lot of time making Joel comfortable with the fact that I have no idea what I’m doing either. But we can figure it out together. What will benefit Joel from pairing with me is discovering the connective tissue of my workflow that you can’t really learn by reading programming books. I liken it to the colloquialisms and slang I learned from TV shows and my friends while I was on my way to become billingual. It can’t be taught, it can only be experienced.

Knowing John, Katie, Morgan, and Joel better; understanding how they think, what frustrates them, what they cares about, what makes them lose sleep at night; that’s how we can all design and develop a better interface to work with each other and build software for other real human beings.

My kind of pairing is simple. It’s loose. All it takes a pair of people working together to achieve something or simply to learn something from each other.

We do not spend 100% of our time on task. Ever. If you think that’s a waste of valuable company time then you don’t understand that the most crucial pieces of the entire machine are the relationships between the humans that keep it running.

After a few successful optimizations for which I successfully added table indices and compound indices to dramatically speed up some queries on very large tables, I found that our Report Card had a ridiculously slow SQL query in it taking basically 50% of the request time.

Much to my surprise, that terribly slow (about 700 ms) query appeared very simple:

1
SELECT  "users".* FROM "users"  WHERE ("users"."username" ILIKE ?) LIMIT 1

ILIKE is a Postgres-specific case insensitive LIKE comparison.

Since I had spent so much time researching, analyzing, and implementing table indices my first instinct was to research the possibility of adding an index to this ILIKE clause and I did find some interesting information about using Postgres’ Trigram extension to make a relatively fast GIN index on this relatively tricky clause.

I got started on adding a migration to our database to enable the pg_trgm extension in Postgres but remembered that database extension support was only added to Rails’ schema.rb files in Rails 4.0 and for now at least we’re still running a patched Rails 3.2 so I wouldn’t be able to make this migration portable without switching to a structure.sql file which is a nope.

Then to clear my mind a little bit I searched for the line of code that was triggering this rogue query.

1
User.where(User.arel_table[:username].matches(params[:id])).first

Now, I understand that using hardcoded SQL strings in Rails feels weird. That said — and I’ll admit I forgot what I base this opinion on — I consider Arel a private Rails API. It may not change often and unpredictably but I will treat it as if can. Harcoded SQL strings on the other hand are unlikely to surprisingly break with no deprecation notice. I’m aware someone could extend this line of argument to say mean things about ActiveRecord but I think that’s silly. ActiveRecord has an API and when it changes we generally tend to hear about it ahead of time.

What really bothers me here is that this User.arel_table[:username].matches(params[:id]) is completely obfuscating the ILIKE statement it generates. If you don’t call to_sql on this thing, or see the full SQL output in your console or on something like Skylight, you won’t notice it’s doing something potentially very slow.

And then it hit me. Why the hell were we doing an ILIKE query? If a user matches the username in a URL, it should be displayed. It’s not like the goal of this action was to display usernames that start with params[:id] and maybe end with something else like a where("username ILIKE ?", "#{params[:id]}%") would. No this was purely focused on dealing with the problem of case. If someone typed in OlivierLacan we want to look for the username olivierlacan or OLIVIERLACAN or OlIvIeRlAcAn.

We could use User.where("lower(username) = ?", id.downcase).first instead and considering we already have an index on the username column this would be much faster. In the best cases that would take the query down to 270 ms.

That’s when I remembered that we had an internal column named system_username where we simply lowercase the username column every time it’s updated. That meant I could let Ruby deal with the (easy) job of downcasing a string:

1
2
3
User.where(system_username: params[:id].downcase)
# or
User.find_by_system_username(params[:id].downcase)

Query speed? 1 milisecond. Instead of optimizing the database for inefficient code, I ended up rewriting the code to be less silly and take advantage of prior optimizations we had (thankfully) done. I didn’t have to install a Postgres extension usually reserved for full-text search, and — more importantly — I didn’t have to create a potentially costly index on an operation (the case insensitive comparison) that ended up being unnecessary.

PS: I’ll be following this post up with a new one detailing my methodology with the more indexing-focused performance optimizations I mentioned at the beginning. If you have any tips and tricks in your toolbag, please send me a quick email to let me know so I don’t look silly. Here are some of mine.

They assume I know about variables, functions, objects, caching, blocks (or closures), loops, and flurry of other programming concepts. I do know about these concepts, at least I think I do. There’s a good chance I would be challenged if I had to explain each and everyone of these concepts succinctly and clearly to someone with no prior knowledge.

Knowing how to use stuff is easy, knowing how stuff works and how to explain it to someone else is much, much harder. Regardless, as a caucasian male programmer, I benefit from the assumption that I must know about this stuff. No explaining necessary¹.

Have you seen a group of programmers talk to a woman who happens to share their occupation recently? If not I suggest you crank up your awareness. Solely due to gender, many programmers will disqualify female programmers from the assumptions I benefit from. Suddenly it becomes “only fair” to ask someone you just met whether they “know how blocks work, right?”.

It’s really fucked up because it’s utterly insidious. What’s really happening there is that dudes have a positive bias towards other dudes. They’re overcompensating. Although I can’t deny that there must be many cases of blatant sexism and superiority complex leveled against women, what I believe to be happening is that when talking to fellow female programmers, men are indeed being as fair as they can be. They don’t make any assumptions. But making assumptions that other guys “know their stuff” is almost second nature.

I’ll admit that I’m simplifying. In many cases (I hope female programmers can testify to this themselves, it’s not really my place to speak for them) these “fair” conversations devoid of any assumptions are laden with blatant condescension and other unsubtle cues. These act like rocket boosters to propel women into a place where they’re made to feel like outsiders, like they don’t belong here.

It’s your responsibility as a professional to call out this bullshit as it happens. If a co-worker suddenly changes their tone when talking to someone of the opposite gender or from a different ethnic background as them. If what used to be a conversation seems to almost imperceptibly shift towards a lecture.² It’s very difficult for someone who’s being put down to call out the person putting them down. Often the offense seems too small to warrant a remark.

Sadly these “little things” — as Anthony Colangelo described them in a recent episode of The Multilogue — do a lot of damage. They’re not as obviously reprehensible as sexual harassment. It’s far too common for people submitted these “little things” to dismiss them and keep their anger to themselves because there are worse problems to be dealt with. The “little things” quickly add up. It’s past time we crush them down before they turn into big things. A single woman leaving the industry because she was made to feel constantly out of place is a tragedy for our industry, and our society.

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.

One of the first thing I notice when pairing with co-workers and friends is whether or not they have what is often described as “option as meta key” enabled in their Shell app.

Even in a basic text editor like OS X’s TextEdit, whenver you type words separated by spaces, you can easily jump to the beginning of each word by using the Option key alongside with either the Left or Right arrow keys. Nothing amazing, maybe you think this is neat.

Well, inside of a Shell, you often can’t use your mouse to place your cursor wherever you wish. This seems backwards (because it is) but it’s a remnant of a world where the mouse didn’t exist. Regardless, many developers eschew the mouse altogether for the sake of keyboard efficiency. Yet it seems like few developers realize that this fast jumping between words is also possible in their Shell.

Terminal

On OS X, in the default Terminal app, when you open Preferences (please use Command + , to do that in any OS X app worth its salt) and go to the Settings tab, under Keyboard you will find a checkbox named Use option as meta key.

Enabling this option will let you fly between words with your arrow keys when holding Option.

You’re welcome.

iTerm

And if you’re one of those fancy cats using iTerm, the process is a bit more involved. Go to Preferences (you better be using Command + , this time), under the Keys tab. In there you’ll see a list of Global Shortcut Keys. You’ll need to add the following two global shortcuts.

Jumping Left

Hold the Option and Left Arrow keys in the Keyboard Shortcut input field, then select the Send Escape Sequence Action, and finally set the Esc+ field to B (for back).

Jumping Right

Hold the Option and Right Arrow keys in the Keyboard Shortcut input field, then select the Send Escape Sequence Action, and finally set the Esc+ field to F (for forward).

You’ll see a warning whenever you save those shortcuts. I believe it’s okay to ignore these unless you already use a keyboard shortcut profile that has the same combinations of keys. In this situation you will have to delete your Profile-specific shortcuts otherwise they will override the global ones presented below, otherwise this won’t work as expected.

This optimization is an example of something you can apply to your life every single day. What task or step of a task are you repeating over and over again. Have you tried to find a better, faster way to do it?

It it seems too difficult? What about working with someone by your side (pairing) and asking them if they have a solution, perhaps? Every single time I pair with someone on our team at Code School I learn something new like this.

What I like even more is that these tricks don’t always correlate with experience. Many people with experience settle for inefficient workflows because they’ve become comfortable with them. Sometimes, that’s fine. Changing a workflow that works can be a distraction. More often though, you can chip away at the little frustrations of your day and hone your tools little by little, until you master them.

PS: If this topic interests you I highly recommend listening the Sharpening Tools episode of the Ruby Rogues podcast with Ben Orenstein. His daily ritual to find something inefficient from the days or weeks before and search for a way to optimize it is an excellent idea.

If you believe this because someone told you: they are wrong. If you believe this because you really want to: please stop.

This idea of evolving above bugs is a very dangerous because it creates an unrealistic expectation. Worse, I see many eager programming beginners (many of them our own students at Code School) subscribe to this idea. I’m sure they believe it’s a manifestation of healthy optimism in their ability to improve as a programmer. It’s not.

Thinking there are such things as programming superheroes that are ten times faster than everybody else and yet somehow leave an equal or smaller amount of bug in their wake is a delusion. These so-called “10X” programmers don’t exist. It’s akin to believing that magicians can really make objects disappear out of thin air.

They can’t. It’s a trick. There is always a trick. The biggest trick of all is the one you play on yourself when you rule out the obvious truth: you cannot fathom how much time these people have spent practicing, failing, hating themselves, trying again and eventually succeeding at fooling you. Penn & Teller aren’t supernatural, their dedication to deception simply borders on mental illness.

You actually don’t want to know what their secret is. That’s because you already know it and you don’t want to accept it. They work very very hard. Harder than you can imagine, and for something you may deem an utter waste of a human life. And they do that because they like it. I could say it’s their passion but as a few people (Avdi Grimm) in the tech industry have aptly pointed out recently, passion is something lovers and parents feel. Dedication feels like a better word. I’m sure Penn & Teller like their job a lot but I’m also convinced that there are times when they hate it too. Saying workers have to be passionate is dangerous because passion tends to smooth over things that shouldn’t be acceptable at work.

With programmers, the trick is similar. Whatever unreasonable amount of time it would take to perfectly understand how — for example — HTTP caching works, there exists people who have spent those hours patiently learning when I really don’t feel like doing that. It’s easy and frankly unfair for me to call these people geniuses and wizards. When compared to my baseline laziness, a lot of people qualify for the genius status. Yet all they’ve done is read code I assumed was probably too hard to understand.

Maybe you told yourself you had too much work to do and couldn’t justify spending time learning about something you didn’t understand. You looked for an easier answer elsewhere. Maybe on Stack Overflow, or in a blog post that matches your precise problem better. Those are useful solutions and I regularly use them myself, but they’re not answers.

An answer or a proof in Math (a subject I nearly failed high school for) is something that displays your clear understanding of the problem at hand and the path you took to achieve a given solution. Even though I hated Math in school (mostly because I disliked school in general), I remember how virtuous that seemed to me. Many students see it as an annoying deterent to cheating, and that seems appropriate.

Finding the solution is something most people can do, even with limited time. Finding the answer requires patience, attention to detail and critical thinking.

“So this is, like, if I took a spaceship to Titan — the moon of Jupiter — and I saw Taco Bell there, I’d be like: ‘No.’”.

This comes from a conversation I had while pairing the other day. Let me bring in some context. I had showed Morgan — the newest member of our Internal Code School team — how awesome Bash autocompletions are inside a shell session, especially when dealing with unfamiliar file names.

For example you want to cd into a folder called banana, all you have to do is type cd bana then hit the Tab key and tadaaa it suddenly morphs into cd banana/ before your very eyes.

Morgan and I had to debug a spec in which we put a binding.pry call from the excellent Pry gem in order to stop execution and fumble around to figure out why a specific test was behaving oddly. We had defined a user variable and I asked morgan to call a method on that ActiveRecord instance this variable was pointing too. As she started to type out the full method name I think I sneakily hit her Tab key with the swiftness of a famished Fox.

To my surprise, Morgan wasn’t happy about this at all. Her response was:

“No.”

She didn’t say that because this little trick wasn’t cool. She didn’t say it because it wasn’t useful. She didn’t say it because it’s kind of a dick move to take over your pair’s keyboard — it is — while pairing. She said “No.” because she didn’t understand how the Pry session could possibly allow her to do this: use autocompletion on a Ruby object’s methods.

After laughing (a lot) she used the sentence I started this post with to help me understand how she felt. Aside from being hilarious, it was a very good example. Magic (in the context of programming) isn’t cool, it’s simply useful — sometimes. What’s really cool, and I bet Morgan would agree with me, is how what appears to be magic actually works. Because there is no such thing as magic.

Do you think I took the time to explain to Morgan how this awesome method autocompletion trick works? Nope. Why? Well, I had no idea how it worked.

Now, thanks in part to a great blog post by Ross Kaff — Ruby, You Autocomplete Me — I do understand how it works. So I thought I’d share it with you too.

Guess what? It’s definitely not magic. Ross’ post didn’t fully satisfy my curiosity so I ended up looking at the IRB::InputCompletor source code in Ruby and it was illuminating.

This is one of the few times in my life when — despite being a Ruby programmer — I have looked at the actual Ruby source code to understand how something works. Every time I discover coding conventions I’m either not familiar with or didn’t expect to find there.

What’s amusing when you start [unweaving the magic rainbow] (http://en.wikipedia.org/wiki/Unweaving_the_Rainbow) is that you discover how simple things actually are.

IRB::Completion uses a gigantic case statement against the inputed text on which completion is attempted. So if you run pry¹ and type:

1
"Howdy".rev

And hit the Tab key, it will complete to "Howdy".reverse. Why?

1. the input before you hit the Tab key starts with a double quote which means IRB::Completion’s first when statement catches it.
2. the receiver (first match returned by the regular expression) is saved to a variable using the $1 global variable².
3. the third match from the regular expression (the second one being the . separating the receiver from method (or method call) is saved to the message variable.
4. Using one of my favorite bit of Ruby introspection, all the possible instance methods available³ to the String class are collected (an alias of the Enumerable#map method) into a candidates array.
5. The select_message class method is called with the receiver, message, and candidates in order to determine what methods should be suggested for completion.

That’s it. All the possible candidate methods will now be displayed in the console as completion suggestions when you hit the Tab key twice. If there is only one match, hitting the Tab key once will complete the method name using that match.

1
"Howdy".reverse

Having people with different skill levels and backgrounds on our team has been a perfect opportunity for me to rediscover the things that I take for granted. When you’re new it’s often difficult (but not impossible) to understand how some of the things you use work. There are many tools I grown comfortable using and yet I don’t fully understand how they work. As I hope I’ve demonstrated, it doesn’t take very long to understand how the tricks are done.

While he was retelling a memorable moment, Anthony reminded me of a funny little concept we came up with while we were studying at Full Sail University: Bose Mode.

Although Bose inarguably makes the best noise canceling headphones and earbuds on the planet, this moniker wasn’t really meant as an endorsement. When this concept emerged, I think we were at the beginning of the second third of our academic path. This meant that regardless of prior knowledge everyone in our class had by this point acquired a hefty amount of knowledge.

With the acquisition of knowledge comes an odd phenomenon: it becomes much more intricate to accomplish something that involves that knowledge. I want to pause here to emphasize the fact that I’m not saying it’s harder, because that’s not true. Knowledge should give you the tools to solve problems more easily, but there’s another edge to that sword.

When taught properly, knowledge is often accompanied with wisdom. I would define wisdom as the humility to appreciate the extent of one’s ignorance. It’s almost a trope but the more you know, the more you realize how much you don’t know and have yet to learn.

I think a byproduct of knowledge and wisdom is thoughtfulness. It can help you make fewer rash decisions by encouraging you to spend more time weighing the variables at stake when solving a problem.

In order to weigh variables, you need to be able to hold them all in your mind at the same time. This is why being a judge must be excruciating.

In this industry of what people sometimes refer to as “knowledge work”, there is an almost unstated understanding that what we refer to as “flow” is the state of mind required in order to make thoughftul decisions while weighing all the necessary variables.

When I try to explain this process to outsiders, I often use a computer as a metaphor — which seems fitting. In order to compute, a computer often needs to download data before it can even parse and analyze it. This is exactly what I believe flow helps “knowledge workers” like programmers and designers achieve. Slowly at first, faster as time elapses, we start placing all the facts about a problem at the forefront of our mind — our Random-access memory.

The reason Bose Mode is so crucial is because any interruption, any loss of focus during such a critical phase means starting from scratch may be necessary. At the very least you will need to retrace your steps in order to make sure you didn’t lose an important fact due to the interuption. When electrical current stops flowing through a computer’s RAM, all the information it contained is irretrievably lost. That’s because RAM is volatile memory, unlike the non-volatile memory of a hard drive or SSD. I find the similarity between humans and machines here striking.

Physically isolating yourself from the sounds of the world is a way to achieve flow which doesn’t rely on the courtesy or cooperation of others. During my time at Full Sail, I’ve managed to achieve flow in a busy Firehouse Subs restaurant at rush hour while sitting under a TV blasting ESPN’s SportCenter. All this thanks to my pair of noise canceling headphones and a base layer of lyric-less music¹ that didn’t subtract from my attention. The advantage of “Bose Mode” is that most actively noise canceling heaphones have an LED which shows whether the noise canceling mode is on. This can act as a mild deterrent to interruptions if people notice that not only you have headphones on, but you’re clearly trying to block out external noise as well.

If you talk to any programmer who travels regularly, ask them what they do on a plane. On flights with no Internet access available, a roomful of strangers in the sky with the right pair of headphones can encourage rare feats of concentration and complex problem-solving. Thanks to Bose Mode, you will also barely even notice the heavy hum of the plane’s engines.

All in all I’d encourage any “knowledge worker” to be aware of how volatile their optimal state of mind to achieve productive work is. You don’t need to receive a popup notification and sound whenever an email comes in. You don’t need to see a little badge number increment on your phone for that either. Email is not chat, it should be able to wait at least a few hours. If you have urgent email, then simply check it more often. At least you’ll be doing that on your own schedule and not be at the mercy of other people’s schedule.

Start using great isolation features like OS X and iOS’s Do Not Disturb modes. On OS X, hold ⌥ (Option) and click on the Notification Center in your Menu Bar (the rightmost icon). This will grey out the icon and will turn off all notifications until you ⌥ click it again. It’s a really useful tool to use when your brain is fully loaded and you’ve achieved flow with the help of Bose Mode.

There are many other ways you can exert more control over what is allowed to interrupt you during your work, but none is as important as the realization of how costly these interruptions are to your ability to do good work with velocity.

Today an ambitious campaign lead by Lawrence Lessig called Mayday reached an incredible funding goal of five million US Dollars which will be matched by another five million US Dollars.

The goal of this fundraising is to create a “SuperPAC” to end all SuperPAC. A PAC is a Political Action Committee which allows US candidates to elections to pool money in order to finance their campaigns. There is enormous abuse and corruption in campaign finance in the United States of America. This matters to the entire world because the entire world is virtually led by the United States of America — its last remaining super power, and the one nation with the greatest stranglehold on the Internet.

The entire unfortunate end of Aaron Swartz’ life was dedicated to doing the most good he could possibly do. For him this meant allowing the public to access publicly funded research currently locked away in the proprietary grips of for-profit publishers who benefit handsomely from access tolls to invaluable public domain research. Swartz also played a huge role in deafeating the greatest threat to freedom of speech and the Internet ever — the so-called SOPA US bill.

Lawrence Lessig was a friend of Aaron Swartz’s. He’s featured in the movie The Internet’s Own Boy quite a bit. It’s humbling to think that despite Aaron having committed suicide a little over a year ago, Lessig has already been working so hard to uphold his legacy. And I’m sure many others have as well.

If you care about justice, freedom, and you believe the Internet is a tool for good, I urge you to watch The Internet’s Own Boy.

If you are an American Citizen or permanent resident, I kindly urge you to take a second and donate to the Mayday campaign.

Why? Because . means every directories here, right? So in your development environment that probably means the cute little directories you expected to be there.

In my development environment (Ruby on Rails), the only thing with spec files in it for RSpec to run is that /spec folder. But what happens in my CI environment if you use a wonderful testing service like Travis CI (like we do) for instance?

There’s a good chance you’re also using the --deployment Bundler flag for bundle install.

And if you ever try this, like I did today. Something really weird may happen in your build, like this:

1
2
3
4
5
6
7
8
9
10
11
12
Could not load native IDN implementation.
/.../vendor/bundle/ruby/1.9.1/gems/backports-3.4.0/spec/tags/1.8.6/core/array/rotate_spec.rb:1:in `<top (required)>': undefined method `fails' for main:Object (NoMethodError)
  from /.../vendor/bundle/ruby/1.9.1/gems/activesupport-3.2.17/lib/active_support/dependencies.rb:245:in `load'
  from /.../vendor/bundle/ruby/1.9.1/gems/activesupport-3.2.17/lib/active_support/dependencies.rb:245:in `block in load'
  from /.../vendor/bundle/ruby/1.9.1/gems/activesupport-3.2.17/lib/active_support/dependencies.rb:236:in `load_dependency'
  from /.../vendor/bundle/ruby/1.9.1/gems/activesupport-3.2.17/lib/active_support/dependencies.rb:245:in `load'
  from /.../vendor/bundle/ruby/1.9.1/gems/rspec-core-2.14.8/lib/rspec/core/configuration.rb:896:in `block in load_spec_files'
  from /.../vendor/bundle/ruby/1.9.1/gems/rspec-core-2.14.8/lib/rspec/core/configuration.rb:896:in `each'
  from /.../vendor/bundle/ruby/1.9.1/gems/rspec-core-2.14.8/lib/rspec/core/configuration.rb:896:in `load_spec_files'
  from /.../vendor/bundle/ruby/1.9.1/gems/rspec-core-2.14.8/lib/rspec/core/command_line.rb:22:in `run'
  from /.../vendor/bundle/ruby/1.9.1/gems/rspec-core-2.14.8/lib/rspec/core/runner.rb:80:in `run'
  from /.../vendor/bundle/ruby/1.9.1/gems/rspec-core-2.14.8/lib/rspec/core/runner.rb:17:in `block in autorun'

The first thing you’ll notice is this super weird Could not load native IDN implementation. error. And you’ll stare at it. You’ll try to poke holes through it like this fella:

Eventually, you’ll Google this weird error message and find this line in the addressable gem:

1
2
3
4
rescue LoadError
  # Cannot test the native implementation without libidn support.
  warn('Could not load native IDN implementation.')
end

Hmm. libidn, what is that? And do I even have addressable in my Gemfile? Nope… Wait, it’s a dependency of launchy and webmock. So… maybe I did something wrong… but WAIT?

Why is the rotate_spec.rb from the backports gem even running in my build?! How is that even…

As a result, bundle install –deployment installs gems to the vendor/bundle directory in the application. This may be overridden using the –path option. — http://bundler.io/

Since I was using the following features in my .travis.yml file:

1
2
3
4
bundler_args: --deployment
# ...
script:
  - bin/rspec . --color --profile --format RSpec::Instafail

The vendor/bundle directory was filled with cached gems before the build started running with bin/rspec .. Because of that single little . RSpec went to town on all the spec files inside of all my gems, and eventually (thankfully) exploded one which had dependencies that couldn’t be satisfied.

I have to thank Josh Kalderimis from Travis CI for his invaluable help figuring this out. Basically the entire “eureka moment” in this post actually went on in his head as I sat there stuck in my Clint Eastwood phase.

This was a good reminder of something I’ve oddly been repeating to people a lot lately: DO NOT FLIP OUT WHEN AN ERROR OCCURS.

Reading stacktraces is most definitely a path down the rabbit hole. Although the first time I encountered this error I didn’t have time to pursue its debugging, I really should have made some time.

As I suspected — and as Josh also found — the stacktrace was a red herring since it was in fact not the cause of the problem, but a symptom. Following the stacktrace only made us more and more bewildered as to why this spec was even running in the first place. Especially since it didn’t happen on my development machine.

Thankfully, Josh started looking at stuff I took entirely for granted. That’s why sanity checking with somebody else is so important in exceptional situations like this. You don’t have to love pairing to use a pair of fresh eyes and sometimes (often) they’ll question something you would have looked at but never seen at the first glance. That’s basically what happened here.

There’s a thing that happens a lot when you don’t really understand something. You go into a “there’s an error message on the screen” mode.

Despite the fact that all you need is to relax and read everything carefully, you (I) tend to get upset and flail your arms uncontrollably at your screen somehow hoping that the singularity will occur and it will develop shame and fix itself to appease you.

That won’t happen. Errors mean you have to grab something that relaxes you (tea, a book, a teddybear) and go into Sherlock mode. Everything is up for grabs. Every little detail matters, especially the most mundane one, like a tiny little fucking dot.

I grew up in one of the less safe neighborhoods of Paris. Back there I knew where and when to be on my guard: mostly at night, or in the quieter spots.

In Montréal, whether it was due the adrenaline rush from the movie, or the excitement of this foreign metropolis I was roaming in, I felt more safe than I had ever felt in Paris.

A few years ago, as I told this story to a friend of mine, a sad look grew on her face. Either she interrupted me, or I stopped talking when I noticed her discomfort, I can’t remember.

She told me why such a seemingly simple story was inconceivable for her. How this reality affected her daily life, even her outlook on other people. How she, essentially, wasn’t as free I was. She told me how vulnerable she felt in situations I would have found mundane: getting in and out of her car, taking a short walk alone from point A to point B anywhere, partaking alone in conversations with unknown individuals or groups. Had I been her, there’s a good chance this moment I cherish in my life would have never happened.

I feel that these are things every man should hear from friends, mothers, sisters, lovers. I don’t mean just hear them, but listen to them. Let them ring in your head until they make you sick.

There’s something heart-stopping about listening to someone tell you the impact that discrimination has had on their life. Ideally, we should all be able to empathize with the misfortune of complete strangers, but sometimes the injustice has to hit closer to home for us to finally react.

All you need to do is reach out to human beings around you. Don’t force them to share something they don’t want. Just be there and lend a friendly ear. You don’t have to try to fix things. Odds are your probably won’t know where to begin. The truth is that there are human beings suffering from things you can’t or won’t see. Some of them are dealing with it in silence. Others understandably refuse to do that.

It’s possible you’re not the one who can do something about it. But maybe you can help empower someone else. By amplifying their voice, helping them cope, lending a hand or an ear.

It might be hard because it’s foreign to you, just as it was to me. It still is, because I don’t have to face these struggles every single day. But at least I’m aware of them.

It’s really difficult to understand that kind of suffering, at least at first. Empathy is tricky when you’re missing so many points of references but it’s not that hard. It took one evening and one patient friend to get me started, to challenge my assumptions on how half of humanity live their life.

All I had to do was start listening to her.

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.

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

In late 2009 a few months after I had started school, my classmate and friend Zachary Nicoll and I co-founded our first little company. Although we were still both in school, by the summer of 2010 we had worked on three professional projects together.

We were doing some sub-contracting work for Envy Labs at some point and we had our own clients to deal with.

During that time, I would wake up at 8 AM (which is ridiculously early for me) and drive to the Envy Labs office in Downtown Orlando. Around lunch time I would head back to Full Sail University to attend a lecture from 1 to 5 PM.

After that, Lab could last between one to four hours. When lab was over, I would head home, do some work for school then start working on our client project.

That sometimes lasted until 3 or 4 in the morning, at which point the exhaustion would lead to really strange arguments about things that really didn’t matter that much. I remember us looking at each other and saying something like “Why are we yelling at each other? Let’s go to sleep.”.

We were burning out. I was burning out even worse than anybody else. I was upset at my closest friends for a project that we had painted ourselves into a corner with and wasn’t even earning us any money.

The most important thing I learned from this experience was the value of a friend’s perspective when you need it most. Zach noticed how bitter things were becoming and I’m pretty sure I was pushing him to do even more. One day, he sent me an email. A long, heartfelt email in which he dragged me back down to earth in kind and calm words.

He said he didn’t sign up for this, that we couldn’t neglect school as much as we had. It made so much sense, but I couldn’t see it before he wrote it down.

Zach was my Burnout Buddy™ that day.

I’ve been trying to be one for the people I work with ever since.

When I started working on Code School in early 2012, another friend from Full Sail had started just before me. It was Adam’s first Ruby gig. After months of courtship the year before, I had finally managed to have him try the language out. He’s one the best programmers I know and I knew Ruby would give him wings, and it did.

In early 2012, there were less than a handful of people working full-time on Code School. Adam and I were both in trenches doing customer support every day along with whatever else we were working on.

During that first year I definitely went through burnout a few times and I saw him go through it too. There were moments when I had to tell him to relax and I hope it helped.

Since I think I’m pretty good at hiding my problems, I don’t think too many people noticed I was spreading myself thin. But then, once in a while Nick Walsh — a very tall front-end wizard at Envy Labs — would arrive at the office ridiculously early (which is “normal” for him) and find me still there from the night before.

He would stand there in front of my desk, cross his arms, and say “Go home!” in a very serious tone. I would laugh and brush it off because: “I was just trying to get that one thing done. I’m fine. I’ll go home in a little bit.”

And I did go home. But then those “stunts” put me out of whack.

First, it fucked with my sleep cycle which is of course fertile ground for more late nights. Second, it sometimes made me resent people who went home regularly every day, seemingly regardless of how busy they were.

Then, and it took some time, I learned from them. Many had kids, a wife, a baby, or pets to go home to. During my worst burnouts I was single, and I didn’t have any pets so it was easy to let the clock run.

Time was this rubber band I thought I could stretch as much as I could. But doing that didn’t lead me to more actual work. It didn’t make me more efficient or better at what I did. It just made me better at doing busy work. Better at staying there, overwhelmed, instead of actually producing something and going home when it was done.

When I eventually got better, thanks to the good examples around me, I made it a point to start checking in on my co-workers to make sure they were okay. This can mean allowing a conversation to run a little longer so you can arrive at more important topics. Nobody tells the truth when you ask them how they’re doing, it often takes bit of bluntness.

When someone shows up to work with circles around their eyes, instead of pretending it’s normal, I sometimes use my cover as a loudmouth to tell them: “Hey, you look like shit. Are you sleeping enough?”.

With the right kind of people, in the right situation, this can be an arrow that shatters their facade and lets you peek into the true state of their mind. But it’s not a panacea, there are many other ways to get people to talk. Some people are like cats, you need to let them come to you. Make yourself available, and please, don’t say “my door is always open”. If it actually was, you wouldn’t need to say that. People would be stepping in already. But are they?

Recently I’ve been taking on more Burnout Buddies. Not just my co-workers but other friends and acquaintances. It feels great because helping someone else can equip you to deal with your own problems better. Or the people you helped can help you back, or pay it forward. It’s a virtuous cycle.

Earlier I was writing a test to ensure that a Hash contains a specific key and value.

1
2
3
it "sets the anonymous key to true" do
  expect(properties).to include { a: true }
end

It then dawned on me that this kind of comparison, while possible in the RSpec DSL with its built-in matchers¹ was actually impossible in raw Ruby.

Take a Hash:

1
x = { a: true, b: false }

Now take another Hash:

1
y = { a: true }

You want to check whether y is included within x or not. So what’s the first thing that comes to mind? For me, it’s String#include?, which works like this:

1
2
"Olivier".include?("Oli")
# => true

This is probably one of the most famous whoa-worthy Ruby demonstrations when someone wants to show the object-oriented power of the language. So naturally, when I’m dealing the x and y hashes above, I reach for include?:

1
2
x.include?(y)
# => false

Well, obviously that’s not (pardon incoming pun) true! Let’s look at the Ruby API docs to see how Hash#include? is defined:

include?(key) → true or false Returns true if the given key is present in hsh.

1
2
3
h = { "a" => 100, "b" => 200 }
h.has_key?("a")   #=> true
h.has_key?("z")   #=> false

If this leaves you puzzled, I can empathize. The fact that the example isn’t even using include? shows that it’s used as a method alias for Hash#has_key? which does have a good name. Hash#include? however, is very poorly named because it breaks a reasonable expectation.

You cannot say that Hash#include? is checking whether something “is included in the Hash instance” because this method only checks keys. If it were checking both the keys and the values then perhaps this would make sense.

The Basic Implementation

So here’s my proposition for a reasonable and simple re-implementation² of Hash#include?:

1
2
3
4
5
class Hash
  def include?(other)
    self.merge(other) == self
  end
end

It seems incredibly simple but by that token, why not offer such a useful method to Ruby developers instead? It seems silly to monkey patch the Hash class for something like this when it could benefit all Ruby developers to have in Ruby core.

Demonstration

And here’s a demonstration of it in use:

1
2
3
4
5
6
7
8
9
10
11
{ a: true, b: false }.include?({ a: true})
# => true

{ a: true, b: false }.include?({ b: false})
# => true

{ a: true, b: false }.include?({ a: false})
# => false

{ a: true, b: false }.include?({ c: true})
# => false

I’m was thinking about submitting this implementation to the Ruby core team to see if they would consider including it in a major version of the language. Obviously, this would be an API breaking change since all existing programs using the current implementation of Hash.include? would suddenly stop working properly.

A way to alleviate that concern would be to use another method name than include which I don’t think is a good idea. That said, I could be convinced that Hash#contain? could be a suitable alternative. This name would prevent an API breaking change and could potentially allow this method to be shipped with Ruby 2.2.

What surprises me is that the very definition of the equivalent Array#include? is hinting at what Hash.include? should be:

Returns true if the given object is present in self (that is, if any element == object), otherwise returns false.

And with that, I rest my case.

I’d like to thank Jim Gay, Pat Shaughnessy and Terence Lee for their feedback and support. I’ll submitting a feature request for Ruby 2.2 shortly unless someone can find a reason for me not to.

Update 1 (August 28th, 2014)

Some time has passed since this post and shortly after Nobu — the amazing Ruby core team member known as “Patch Monster” — created a patch that actually implements this proposal, albeit with name I find confusing.

After talking with some Ruby developers, including Adam Rensel who works with me at Code School and also often has the need to check whether a Hash is partially or completely included in an other Hash, I settled on a better name for this method: Hash#contain?(Hash)

I know I said I would be submitting a feature suggestion to Ruby Core and sadly I haven’t done that yet because I wanted to make sure that this wasn’t frivolous. But I swear I’ll do it before RubyConf 2014.

To be honest I wish we could extend the capabilities of Hash#include? because its current implementation seems woefully simplistic. It’s a mere alias to Hash#has_key? which is inconsistent with the meaning of “include” in my book. I believe that if Hash#include? (a real one, not an alias) receives a Hash, it should do actually compare the two hashes (both keys and values). If it receives a String or a Symbol, it should defer to Hash#has_key?.

Update 2 (March 19th, 2015)

After a busy end of 2014 I finally found the time to submit a proper feature proposal to bugs.ruby-lang.org.

The feature is being debated with fellow Rubyists at the moment.

Update 3 (November 9th, 2015)

After some stagnation, the feature proposal was discussed in two separate Ruby core team developer meetings. First on May 14th, 2015 and then this morning for the November meeting. Matz said he favored a comparison operator (<= or >=) because it’s less ambiguous than contain?.

This means that the syntax I originally proposed would evolve to something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ a: 1, b: 2 } >=  { b: 2 }
=> true
{ b: 2 } <=  { a: 1, b: 2 }
=> true

# also
{ b: 2 } >=  { b: 2 }
=> true
{ a: 1 } >=  { b: 2 }
=> false

{ b: 2 } <=  { b: 2 }
=> true
{ b: 2 } <=  { a: 1 }
=> false

I have to admit I was originally surprised by Matz’ proposal (it was early) but I’ve since then been convinced by its versatility and simplicity. I really hope it can be included in Ruby 2.3 for the December 25th release. That would be quite the Chritmas present. :-)

A word about the load $PATH

The Sublime Text documentation on this tool does explain where it’s located (/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl) but it assumes you have ~/bin (or /Users/username/) in your load path ($PATH) which is downright silly. There’s a better way.

The /usr/local/bin is in the load path by default on OS X, so it’s a much better place to symlink (create a symbolic link — or shortcut) that will allow you to run the subl utility from your Terminal app.

First up, check your own $PATH by running: echo $PATH. This is what mine returns:

1
/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin

As you can see the /usr/local/bin path is included by default on OS X.

Installation

Note: These instructions assume you’re using the Terminal app out of the box, without ZSH or any fancy prompts like that. I trust you will be able to adapt these instructions yourself if you do.

1
ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/sublime

Yes, I name the symlink sublime instead of subl because I believe you should always be explicit. You should never have to type the full word anyway. Typing sub + Tab should auto-complete the full name of the symlink.

Testing

Open a Terminal window and run:

1
sublime ~/Documents

or

1
2
cd
sublime Documents/

or even

1
2
# to open the entire current directory
sublime .

Conclusion

Now you don’t need to get out of Terminal to simply open a file or a folder, you didn’t have to add an “alias” or yet another bin directory to your .bash_profile which the official instructions given by the Sublime team seems to recommend.

Have fun, Sublime is a great editor. Check out the most recent beta release of Sublime Text 3.

You can find more information about the credible allegations that led to Jacob Applebaum’s exclusion of the Tor project and many other cryptography-related communities in this Daily Dot piece

If you’re technologically savvy, there’s no doubt you’ve been watching the information being released about the myriad of NSA intelligence collection programs.

I don’t think I’m qualified to comment on their extent, legality, or even if I know what to think of them.

However, I think you should watch this chilling presentation by Jacob Applebaum at the Chaos Communication Congress in Hamburg, Germany today.

Yes, you should spend an hour watching this. But if you chose not to, let me boil it down for you: an American governmental agency mandated by the Congress of the United States of America has been systematically subverting and sabotaging security protocols designed and manufactured by foreign and American companies.

This means that instead of reporting and encouraging American companies to fix extremely serious security vulnerabilities that put US businesses and private individual at risk of corporate espionage or privacy invasion by anyone — terrorist groups, foreign governments, criminals, hackers, competitors — the NSA has been subverting these security vulnerabilities to further its own goal: communication omniscience.

I believe in democracy, freedom of speech, and the privacy of all law-abiding citizen. The NSA doesn’t, and nothing stands in their way.

The German newspaper Der Spiegel has more about these revelations in a multi-part piece titled Inside TAO.

On September 3rd, 2013 GitHub announced a long awaited implementation of two-factor authentication on github.com. Of course I immediately turned that feature on, and you should too.

Authentication failed

After setting up 2FA on GitHub, I moved on and forget about it. I imagined that my week would go on merrily, until one fateful day when I jumped into a repo and this happened:

1
2
3
$ git pull
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/codeschool/kraken.git/'

I clearly remembered pulling from this same repository without a hitch a few weeks prior. How could my authentication suddenly fail. That damned osxkeychain credential helper felt like a perfect culprit, since I had issues with it in the past.

Strange. I definitely typed the correct password here.

Remembering that git has a way to talk to Keychain (the credential helper), I thought maybe it had stored the wrong password so I checked the credential helper for signs of life:

1
2
3
4
5
git config --global credential.helper
osxkeychain

$ git credential-osxkeychain
Usage: git credential-osxkeychain <get|store|erase>

Seemed all right. Maybe Keychain had the wrong password stored somehow?

Keychain

After checking my own Keychain, there was indeed a record in there that matched https://github.com:

Since this obviously wasn’t working I checked the info for that record:

It all checked out. The password was correct since I had just logged into github.com itself using it. You can even see that the git-credential-osxkeychain binary is allowed to access that credential from Keychain in the Access Control tab:

So it’s not an access problem. What the hell is going on here? I decided to delete the Keychain record for github.com and try to re-submit them.

1
2
3
4
5
$ git pull
Username for 'https://github.com': olivierlacan
Password for 'https://olivierlacan@github.com':
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/example/thing.git/'

Still not a fan of my password, uh.

It all makes sense now!

In a last effort, I googled the term “https github error” and found a GitHub Help article on HTTPS cloning errors. Since cloning didn’t work either, I thought it could be useful. And that’s when the answer jumped at me.

If you have enabled two-factor authentication, you must provide a personal access token instead of entering your password for HTTPS Git. You can create a personal access token for accessing GitHub by going to the application settings page.

I willingly setup two-factor authentication on github.com and expected that my single-factor password would still work to authenticate through HTTPS via Git. And I probably glossed over some essential warning copy while doing so.

Creating a new Personal Access Token on GitHub is easy and you get a hash to use as a password. That is what the osxkeychain credential helper saves to use whenever you use HTTPS to clone or pull GitHub repositories.

After the first prompt for credentials (on clone or pull), Git saves the credentials in your Keychain and everything works as it’s supposed to.

Conclusion

Remember to make sure that you do have the keychain credential installed. If you do, you should see this:

1
2
3
4
5
git credential-osxkeychain
usage: git credential-osxkeychain <get|store|erase>

# to configure git to use it:
git config --global credential.helper osxkeychain

If you don’t have the credential helper installed or if you’re using an operating system other than OS X, read GitHub’s new Caching your GitHub password in Git guide.

Outdated credentials stored in Keychain Access for github.com can also cause issues. GitHub now has a guide on how to delete outdated credentials from either the Keychain Access interface or from the credential helper.

PS: I highly recommend using GitHub’s Hub wrapper for Git since it allows you to clone repos with a simple git clone rails/rails command. It automatically fetches the full HTTPS URL for you and uses that for the origin remote.

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.

It’s not really about attempting to write and failing, it’s the perpetual problem of finding every possible distraction to keep me away from the keyboard so I can’t discover that — in fact — I have nothing to say.

I know I have things to say. I know some of them are relevant to a great many people because they are relevant to me. Despite being odd and loudmouthed, I’m not so different from everybody else.

Yet, I make myself overwhelmed with things to do, and places to go to. I convince myself that there’s a perfect environment in which the words will flow through me and out onto the screen. When I get to that perfect environment, I find a reason:

• I want to talk to this person, maybe they’ll inspire me
• I need this drink, and then I can start
• There’s someone out who sent me an email and is waiting for a reply, why make them wait a second more?
• Shit, I need to pee now
• Hmm, I’m sure checking Twitter or Instagram won’t distract me
• Oh I know, I’ll take out my notepad and start writing with a pen instead!
• Wait a minute, I had a nice draft on a similar topic before, I should finish that instead

So many excuses.

What’s even more enraging is that this digressive nature plays a great part in my creative thinking and problem solving abilities. But in moments like this, when writing isn’t the relief but the task at hand, it becomes so difficult to turn down the volume of a world I find so exciting and inspiring. It feels like disconnecting from the very thing that keeps me alive just so I can better talk about it.

It feels hard, but the solution is obvious: start writing.

Hello everyone,

I’ve been putting off writing this because I like to think of myself as feisty and I didn’t really want to admit defeat.

I’ve been working in the US for the last 2 and half years under a non-renewable work visa that is set to expire on December 15th, 2013. The USCIS is kind enough to extend me a grace period of 60 days beyond that date during which I can remain in the US but will no longer be allowed to work in any capacity.

That means that unlike you suckers, I’ll be on vacation in 25 days. Haha.

I spent about an hour on a call with an immigration attorney from San Francisco. Unsurprisingly, she deals with a lot of similar cases, and she was recommended to me by a nice British Ruby developer I met at RubyConf and who — like a bunch of other recognized or famous folks in the tech industry — obtained a prized O-1 visa. Unlike the H-1B visa I unsuccessfully applied for earlier this year (65,000 slots, over 150,000 applicants), the O-1 is not tied to a single employer-sponsor but has much stricter requirements — it’s for aliens with “special abilities”.

Since I haven’t practiced shooting gamma rays out of my finger tips in quite some time, this is a bit of a longshot. I’ll most likely need to put on my writing cap to publish articles (in major publications if possible), apply to speak at more conferences, and hopefully extract an ebook or print book out of my brain with forceps. If you or anybody you know can help me in this process, I’ll repay you in mountains of authentic French cheese, pastries, cookies, wine and other delicacies.

The most sensible option for me beyond December will be to fly back to France and scramble to setup a way for me to work for Code School either as a third-party or as a foreign employee. I’ve talked with an American citizen living in France about this quite a bit, and I’m doing my best to figure out how to navigate the extremely business unfriendly French legislation to avoid being buried in taxes if I’m paid in dollars while living in Euroland with 20% VAT and 50% professional taxes.

The San Francisco attorney advised me to avoid travelling back to the US with an O-1 or H-1B application in process. That’s because the USCIS (Citizenship & Immigration Services) is very sensitive about “immigration intent”. You see, while I’ve been living legally in the US for nearly 5 years, I’m a “non-immigrant”. Clearly I’m still checking out this whole USA thing, and I need to hear about payment plans before making up my mind.

My goal now is to bump up my profile (if you thought I was self-centered before, boy you’re gonna love me next year!) as much as I can to make the O-1 possible in the medium to long term. Meanwhile I’ll be getting ready to re-apply for the H-1B on April 1st, 2014 despite the poor odds. Both O-1 and H-1B are costly (especially when using legal counsel) and time-consuming affairs, which means it’s very likely I’ll be reducing the amount of hours I work each week to a minimum. Slap me if you hear me complain about anything else, because I’m extremely fortunate to be able to work with all of you, but not being able to put 100% into Code School enrages me. I’ve never been more proud of anything else I’ve ever worked on in my life, and I don’t intend on giving up because of archaic immigration legislation.

Now if you want to see the bright side of this, realize that a guy who can get one of the most envied Health Care coverage in the world, who can live in the city with unarguably the best selection of cheese, bread, meat, chocolate and alcohol the universe has ever known, who can quite literally live like a king by taking a bus that passes through the royal courtyard of the Louvre Palace, that this guy would rather be hanging out with you in sweaty old Orlando, Florida — where people don’t know how to drive very much but at least they’re not honking arrogant smelly pricks.

So, there. Cuddles. And prepare for regular French onslaughts.

Olivier.

I’m going to write about this a lot more in the future but for now I don’t really have it in me to add much. Wherever you’re from, if you’ve been or are in this situation, I’d love to hear your story.

“I think empty folders and empty files are two of the pivotal innovations in Rails that have encouraged us to write clean applications since the framework appeared.” — David Heinemeier Hansson during his Keynote at RailsConf 2011

Empty files and folders, isn’t that just clutter? If the files cause your application to load more slowly (because Rails needs to load them all) then yes, maybe it’s a good idea to get rid of the empty files.

The empty folders, however, are a gift that keeps on giving. They invite all developers who use Rails to organize their codebases in the same fashion. They ensure that you can:

• look in test/ for tests
• expect application-specific CSS files to be app/assets/stylesheets for any application CSS files
• search in app/assets/javascripts for any JavaScript or CoffeeScript code
• etc.

I was reminded of the value of these folders this week as I started updating 35 of our Code School Rails apps to add a third-party JavaScript library. All I had to do was drop a JavaScript file in vendor/assets/javascripts. Semantically the location of the file implies that the code is not application-specific and from a third-party, I don’t need to document that in any other fashion.

Thanks to the often derided (deservedly so) Asset Pipeline, I can be confident this new file will be added to the load path and available for me to require inside of app/assets/javascripts/application.js (or equivalent CoffeeScript files).

One of my favorite feature of Apple’s MacBooks is the Magsafe power adapter. I’m not talking about the fancy magnetic connector that snaps out when the power cable is accidentally yanked in order to prevent the computer to be hurled towards the ground as well. That thing is actually a sexy feature for which the value proposition is quite obvious to most customers. No, what I really love is the brick itself, it’s an often overlooked work of exquisite attention to details.

Apple Magsafe Power Adapter

First, this custom-designed power brick is beautiful. Unlike most other laptop manufacturers, Apple didn’t pick a huge off the shelf power adapter unlike Sony, Samsung and other manufacturers who usually do a good job of valuing (or cloning) design. You could be cynical and see that as a ploy for Apple to sell non-standard plugs at a high margin. Sure, they’re non-standard and Apple likes to make a profit. But when the standard sucks, why tolerate it when your goal is to offer a better product experience?

Sony Vaio Power Adapter

Second, look at the prongs sticking out of the brick. In North America, these are foldable, which allows the brick to become a perfect square. That’s a dream when traveling light as you can fit this power adapter in the smallest bags (or purses).

Third, the reason you see a line separating the actual prongs and the rest of the power adapter body is because the module is (easily) removable. By sliding it out, you can swap it for a longer extension cord in case you’re sitting in a coffee shop with a distant power outlet. Better yet, this makes the body of the adapter universal. It can be used anywhere in the world as long as you swap the proper plug for the region you’re travelling to. Of course Apple sells an Apple World Travel Adapter Kit to solve that.

Last, and defnitely not least, the sides of the brick have little retracktable arms you can pull out to neatly fold the cable that connects directly to your laptop. At the end of that cable, a small plastic holder allows you to secure the loose end of your cable.

Regardless of wattage requirements necessary for different laptops, every single power adapter Apple ships behaves the same way, even some of the tiny power bricks that ship with the iPad and come with a USB cable instead. This is an amazing convention that keeps on delivering value to users, and I can’t remember a recent time where Apple touted it in their marketing material.

First, I made sure I had my portable hard drive back up my system using Time Machine, to account for dire situations. I have most of my absolutely crucial files backed up to Dropbox continually anyway, but it would be a pain to re-install everything if I didn’t have a Time Machine backup handy.

The Mavericks update process was uneventful and took about 35 minutes which were a perfect excuse to brew some tea and read a few pages on the hammock. Tough trade we’re in.

My first step after restarted with a wall of Californian water was to jump to System Preferences > Security & Privacy since two apps I use were asking for me to turn the “assistive devices” feature back on. This feature has basically moved around the System Preferences in every recent release of OS X so it’s a good thing Mizage (the makers of Divvy) offers a guide. Sadly their guide is out-of-date (made for 10.8), so here’s where you can enable access for assistive devices on 10.9.

I enjoy the fact that this is now a whitelist instead of a global toggle as it was in 10.8. I can now control which apps can take control of my operating system’s input devices, instead of granting that privilege to anything I have installed. Thumbs up for security there, Apple.

Second step once TextExpander and Divvy were back in service was to open the Terminal app and run brew doctor. Homebrew is a package manager for command line utilities that makes life extremely easy for developers. If you don’t already use it (or you still use the antiquated MacPorts) you should.

XQuartz started being necessary (as a standalone install) since 10.8 I believe, and it’s fairly simple to download and install, especially since the Homebrew folks do most of the work for your.

Next step was xcode-select --install which will open Xcode and make it prompt you to download and install Command Line Tools. Remember that the CLTs which Apple now ships independently of Xcode make it unecessary to use Kenneth Reitz’ nifty OS X GCC Installer which was often necessary with OS X 10.7 (Lion) and 10.8 (Mountain Lion) when Apple screwed up most Mac development environments pretty badly.

I’m not exactly sure why autoconf, automake and libtool showed up as unlinked. This may have something to do with the upgrade process messing with the file system. mysql is something I manually uninstalled prior to upgrading to Mavericks, so you can ignore that one.

Fixing those is rather easy.

After all this, re-running brew doctor is a good idea, to see where things are.

Since I couldn’t brew link mysql because I had uninstalled it, I googled around and found that brew remove --force mysql would get rid of it altogether. Nifty trick, especially since Homebrew insisted I had “multiple versions installed”. I didn’t. I never use the damn thing. Switch to PostgreSQL by the way, you’ll thank me in a few years.

Finally a little brew update to fetch new formulae (recipes to install packages in Homebrew parlance). One last brew doctor and the satisfying result:

Your system is ready to brew.

State of the Rubies

I use rbenv to manage a myriad of different Ruby versions required by old apps I built in college which use Ruby MRI 1.8.x, somewhat old apps I built after college which use Ruby MRI 1.9.2, and most of our Envy Labs and Code School apps which use various patch levels of MRI 1.9.2, 1.9.3, 2.0.0, JRuby, etc.

After using RVM for several years, I highly recommend rbenv because of its simplicity. There’s a caveat. I’m fairly familiar with Unix by now, and it’s very likely that if you’re not as familiar you will prefer RVM overall. That said, as someone who easily becomes frustrated with latency, I’m under the impression rbenv is faster. It’s very likely bias on my part because I used RVM a while back on older machines and because I’ve become better at streamlining my system. Aesthetically, I find myself enjoying the simplicity of rbenv as well.

I use rbenv with the following plugins installed in ~/.rbenv/plugins:

• rbenv-bundler which prevents me from having to type bundle exec <gemname> for gems with executables installed via a project’s Gemfile.
• rbenv-gem-rehash which automatically runs rbenv rehash for you after installing gems with executable binaries so you can instantly use said binaries without reloading your prompt or manually running rbenv rehash.
• ruby-build which allows me to run rbenv install 2.0.0-p247 directly when I need to install a Ruby version.

After installing Mavericks, rbenv was fully functional and I managed to install Ruby 2.1.0-preview1 without a hitch. Better yet, all my existing Rubies worked fine and I was able to fire up Powder — a lovely little gem I use to manage Pow for all my Rails projects so I don’t have to manually setup their rails server on different ports.

This was by far the smoothest OS X upgrade experience I’ve ever had with a Rails development environment installed on my machine. That doesn’t mean I won’t run into some hiccups later, but it’s reassuring for people like me who stay away from upgrades for fear of having a day of work ruined trying to get things back to normal.

PS: If you enjoy all these talks of tools, you should check out my toolbelt.

Sadly I have a tendency to become blind to low-hanging fruits. The tiny features that can drastically affect our users’ experience but may not involve impressive engineering feats.

Last year I worked on adding the ability for Code School teams to have Managers. No, we weren’t trying to introduce middlemen between our team members and their learning. We had been receiving an increasing number of customer support requests from people who worked in companies where developers and designers were using Code School. The people who reached out to us weren’t themselves developers or designers but they needed to be able to invite new employees to their Code School team. Perhaps they were in charge of all company expenses and therefore weren’t comfortable giving the company’s credit card information to another employee.

We hadn’t considered this yet. It would have been hard for us to derive a usage pattern from a situation we weren’t familiar with within our own team at Envy Labs. Instead of trying to predict that people would need a feature like this, we reacted when our own paying customers proved to us that it would be worth spending time developing it.

We started working on the feature, and during one our pairing sessions, I decided (and my pair agreed) that it would make sense for people who created a Code School team to not become a playing member of that team. We made it so that they would be offered an easy way to join the team and have access to all our content, which meant using up a paid seat.

I know what you’re thinking. It makes no sense because this person just paid for a subscription (which defaults to one paid seat) and they can’t access our content until they express the intention to do so. Through a combination of over-focus on the details of the feature, and over-exposure to the customer support data that prompted this feature to be considered, somehow, it made absolute perfect sense to me at the time. I thought it was fucking brilliant.

Except it so very much wasn’t. After a few weeks we started receiving complaints from people who had just subscribed to a team account and said they couldn’t access our courses when they tried right after subscribing. At first I scoffed with the overconfidence of someone who has come to trust something they contributed to building way too much, and then it hit me. Oh shit, they didn’t notice the button and the carefully worded copy that offered them to join their team as a playing member.

“Oh, people”, I thought to myself. “Can’t be bothered to read an easy little button, huh?”. Bullshit! When a user proceeds with an action (subscribing) that involves upfront payment, they except the goods to be given to them as soon as the payment clears. What did I do? I introduced an extra step in that process, in way that would have made Windows Vista proud.

And this is where I get to my point. This is the code that ultimately determined this behavior:

1
2
if subscription.team?
  ensure_owner_in_members

And this is all I had to do to provide a much nicer initial flow to our team customers:

1
2
3
if subscription.team?
  ensure_owner_in_members
  ensure_owner_in_managers

This was a minuscule feature. I really can’t call it a bug fix. There was no bug in here, only intentional behavior, however poorly thought out. Yet, the impact this feature had on our customers wasn’t miniscule at all.

PS: I recently asked the Tender team to add a keyboard shortcut (the mighty Command + Enter) to submit a comment in their customer discussion interface. Our community manager, Joseph, had mentioned to me that he mashes his Tab key 5 times in a row and presses Space in order to comment & close a support discussion on Tender. It has become muscle memory to him, so it will be hard to remap that behavior to the new Command + Shift + Enter shortcut that allows him to do that in a single stroke, but thankfully it will stave off his carpal tunnel syndrome.

Julien, the Tender developer who took care of this, inspired this post with his response when I thanked him in a tweet for the feature:

https://twitter.com/asciithoughts/status/370314878470193152

Recently, I started becoming aware of a downside to increasing expertise in a specific domain and the attention to details it affords. I refer to it as “Expert Bias” and define it as follows: the inability for a person who has mastered a skill to understand how useful that skill can be to laypeople.

It’s rather broad, so let me clarify. As a computer programmer, I’m surrounded by scores of intelligent people with a knack for problem solving. They like to better themselves in order to improve their workflow and to create better, and more maintainable software for their customers and for themselves. They, and I, see this pursuit as something that can obviously benefit the end goal: solving people’s problems.

The problem I see lies in the inexorable erosion of empathy that seems to accompany the accumulation of expertise. Mastery requires perpetually increasing one’s standards in order to achieve better, faster, stronger work. In doing so, you disconnect yourself more and more from the common tastes and standards of the people who need your help most: business owners, creative minds, and customers. All of them who seek your expertise to help solve their problems.

That disconnection is pernicious. People in domains that require highly specialized knowledge often marvel at the illiteracy of others in that specific domain, especially if they’re expected to interact with those Others.

In my world, those Others are customers, although we like to refer to them as students. Those students give us money in exchange for knowledge. They need this knowledge and trust that we can provide it to them.

The proposition that we can teach them what we know in exchange for money holds as long as their skill level and ours are within the same order of magnitude. They have some knowledge. We have some other knowledge. They wish to acquire the knowledge which we have and they don’t. It is possible for us to have a mental image of the skills they currently possess and imagine a path from their existing knowledge to the set of knowledge we aim to impart on them.

An issue arises when the amount of knowledge we possess is radically different from our students. If operating a modern computer is already a tedious process for them, there’s a good chance it will be much more difficult for us to:

1. Empathize with their current state of knowledge and what they currently struggle with.
2. See a path between their current knowledge and the knowledge they wish to obtain from us.

Tim Van Damme once gave an excellent demonstration of this problem using the slope of a mountain. From the base of the mountain, the top seems unreachable. From the top of the mountain, it doesn’t seem like the climb was so hard after all.

You, at the top of the mountain, tend to forget the fear, the confusion, the shame, the sweat, the impasses, and the temptation to give up you had up until the summit was within reach.

You are not the most suited to give advice to the people at the base of the mountain. Sure, this has a lot to do with emotions. If not everything. It’s much easier to empathize with people you know, or who are not so different from you. From the perspective of the beginners, it’s easy to develop an inferiority complex or find it aggravating when people who seem to have it all figured out try to help you.

But I think it’s not just about emotions. Human beings have an extremely selective memory. We’re great at remembering the hits and forgetting the misses.

To stay vaguely in the realm of mountaineering, think of a brick wall. To me that’s what getting started as a beginner feels like: standing in front of a two-story tall wall separating you from a fucking mountain of knowledge. Before you can even start to worry about the mountain, you’re left without a clue as to how to get past this wall.

Experts are masters at forgetting the wall even exists.

Can you blame them? If you spend your days miles high on a mountain top, what’s a two-story wall to you?

The base of that brick wall is littered with the hopes of people who were given advice by people standing on top of a fucking mountain.

Thanks to Tim’s metaphor, it’s easier to understand that the people best suited to give advice to the wall climbers are the people who just figured out how to get past it.

It’s true that expert climbers have better technique. They know how to deal with severe weather during a high altitude climb for instance. But all that knowledge is not going to help the bricketeers right now. At best it will confuse them.

What’s worse, the experts have probably forgot what it’s like to climb masonry. They don’t have to deal with that anymore. They have bigger fish to climb.

That last part gnaws at me perpetually. I obviously strive to become the best I can be at what I do, but I do care about the people climbing behind me. More importantly, since I love building products, I care about the people whose problems I’m trusted to solve. What if I’m climbing an ivory tower and my trophy will be to lose all empathy?

I need my students. They’re not a means to my end, they are my end. They fuel my passion, they provide me with an endless stream of problems to solve. What if in the process of becoming better at solving things I became unable to care about what I solve? If this sounds like the fiery pits of cynic hell to you then maybe we have a shared incentive to help each other re-focus on what matters.

The way I achieve that renewed focus is by running all the way to the bottom of the damned mountain. What does that mean? Well for once, you can try spending a whole day doing customer support instead of rushing to ship that new feature you’ve been working on for weeks and months. You might just realize that, in fact, most of your customer’s problems are much easier to solve than the overengineered solutions you like to challenge yourself with.

The breeze on the way down from the top of the mountain is quite refreshing. When I get back to the base, the scenery is always much nicer than I remember. Things are much clearer somehow, and it helps me remember what really matters. Yes, I can’t see miles ahead any longer, but the beautiful mountain of knowledge I was sitting on becomes apparent. It’s harder to take it for granted, or to feel like an impostor because it seems like you’re making it up as you go along.

The people at the base of the knowledge mountain aren’t simplistic barbarians kept away by the brick wall. They’re curious souls with simple problems that I might just have the ability to solve. They’ll be thankful and I will feel amazing having shipped simple and efficient solutions to simple and real problems.

I understand intelligent people — programmers especially — are attracted to hard problems. I’m not, or at least I try not to be. The simpler problems may not look like they amount to much when looked down upon, but they matter to many people. It’s easy to forget how much.

What’s the point in learning magic if you don’t use it to help and delight people?

PS: There’s apparently a phenomenon referred to in psychology as “The Expertise Bias” which I didn’t know about before writing this piece.

PPS: Kathy Sierra posted a great video entitled Expertise Induced Amnesia from a different domain — horse-riding. In it Mary Wanless explains the issue I’ve tried to surface in this post in a much more concise way. I highly recommend watching this.

The sun was warm but at an angle low enough to not even make me sweat. There were a few clouds in the sky, tall beautiful ones that bring out the rich blue and green colors all around. I felt so good after a few paces I lifted my hands up and let the wind dance through my fingers.

I often do this. I bought this bike — a road bike, not a fixie, I enjoy well-engineered bikes, not sweating and breaking with my feet to feel authentic — about a year and a half ago. I’ve ridden quite a few different bikes throughout my life:

• A crappy golden cross bike my parents got me at a garage sale that looked like a beat up Harley
• A cheap all-terrain bike we won with supermarket loyalty points and which disintegrated (chain and all) in the middle of traffic while I was riding home from work in busy Parisian boulevard traffic
• A fancy urban bike with front and back suspensions, a kick-ass black design, a comfortable seat for the taint-hating Parisian pavement & sidewalks that I rode with in Paris through traffic jams and got me to college faster than any engine-bearing vehicle in the city could
• And the most recent, my first road bike, which I decided to buy when I realized that Central Florida was lizarded (can’t believe that’s not a verb here) with beautiful bike trails that let you see much more of the Florida wildlife (lakes, fields, rivers) than you would ever see otherwise

Since it was my first road bike, it took me a while to feel comfortable riding it, especially since it’s hard to use a bike as a commute vehicle in Florida. For most of the year it’s too hot to ride one comfortably, but more importantly I promised myself I would never ride outside of trails. Because Florida is so vast, it’s extremely uncommon for drivers to cohabitate with cyclists. Unsurprisingly, since drivers don’t expect cyclists, they don’t account for them in their manoeuvers. It’s easy to blame the drivers, since too many people I know were seriously injured in bike/car collisions, but not every driver in the world has been subjected to the constant flow of brazenly inexperienced cyclists a city like Paris has. That shit — along with smart cars, vespas, buses and taxis — turns you into an expert defensive driver, and a misanthrope.

Anyway, I fell off the damn bike. She doesn’t deserve that moniker, although I still dislike how easily road bikes swerve when they’re rarely ever used for sharp turns, that makes no sense to me. My point with the long history of my bike ownership was to show that while I’m not an accomplished cyclist, I’ve been around the block on a bike.

Since road bikes sacrifice comfort for aerodynamism, they invite dangerous behavior when riding in long straight stretches. You perk your head up, lock your feet and knees in a stable stance and off go the hand, caressing the flow of oxygen drifting by.

It’s a design flaw. Having handlebars slight elevated compared to the seat makes sense, it also lowers you and the bike’s center of gravity. The front axis not being so fucking loose wouldn’t hurt either. But I’m doing that thing when you hit a terrible shot at ping pong or tennis (or baseball, let’s make it colloquial) and then immediately look at the damn racket as if it was operating on its own and you weren’t the single point of failure.

Yes, I got cocky. I felt awesome. I felt safe. Not invincible, I’m not that stupid, but safe enough. It’s been years since I fell off a bike this hard. I think the last time was when the chain and entire front wheel axis of a cheap bike decided to bail when I was crossing a very quiet street by a lovely little bridge south of the Seine. I had it easy, just a bleedy elbow scrape and some minor carpet burns on my hands. Some cold water took care of it.

This one wasn’t bad but it could have been. It might have been a bump in the road or I just lost my balance and it all went really fast.

I think my shoulder hit the pavement first, which would explain the small hole in my brand new t-shirt and the friction burn. Then came something I really didn’t like. I wasn’t wearing a helmet — doesn’t really work with the long hair, although I often wear one if I’m going to ride on roads with motor vehicles — so while it’s possible that the contact of my head with the pavement made my lose a few seconds I remember the very uncomfortable feeling of the pavement rubbing against my head (at about 5 to 10 miles an hour and decelerating). I really didn’t enjoy that, thankfull I quick rolled on my thigh and hip.

That didn’t feel great on the hip but at least there’s more bumper there. Can’t wait to see the size of that bruise though.

I quickly got on my feet and a minivan that was following behind me slowed down and parked, the driver asked if I was alright after lowering his side window. I ran a quick mental check list:

• no gushing wounds: check
• no weird feeling of nausea/lightheadedness or stars from the head trauma: check
• wobbly legs but no apparent foreign objects: check
• fingers intact (my livelihood, that would suck): check
• phone in working condition I’m just trying to save face: check
• within reasonable walking distance of my car (less than 5 min): check

I told the nice human being that I was alright, and dragged my bike away from the path. The bike path was large and well delineated but right alongside the roadway. Good thing I make it a habbit to stop fucking around the with no handlebars thing whenever a car is too close or this could have gone wrong. There was no traffic anywhere close to me when I fell. But I got really lucky on the obstacle (during my fall) front.

It’s several hours later now and while some of my burns & scrapes are painful I’ll survive and my head trauma is extremely minor with no bleeding. I’ll get it checked out as soon as I can figure out where the nearest urgent care clinic is (this clearly doesn’t warrant an Emergency Room visit).

That said the very fact I decided to write all this down (after calling a friend to see if someone can drive me to a clinic, calm down) shows that accidents like this cause reflection. I subscribe to the idea that failure isn’t necessarily something you can learn anything valuable from. It teaches you about failure, that’s about it, maybe about caution too. I will not cease to ride my bike with no handle bars, and while I will make it a point to wear a helmet whenever I’m close to a roadway, all the precautions in the world won’t change the fact that at some point in the future, I will fall off my bike again.

It will hurt, it will piss me off, I will have let my guard down, because it’s impossible to be constantly cautious. Or if it is, I don’t want to be. I’d rather live and lick a few mean wounds once in a while.

No what I enjoyed about this incident is that it has shown me that the minimum amount of security I practice is reasonable. I have two first aid kits at my house, sufficient material to clean up and dress wounds. I know where the nearest urgent care and ER are. I keep enough battery in my phone to be able to find help if necessary. I know not to lie down after any head trauma, to stay alert and make sure someone I know is aware of my state so they can help me out if something goes wrong.

In other words, while I fucked up, my system worked. If hadn’t been able to use my own system, I trust that my fellow human beings’ systems would have worked to get me help. Like many accidents, this is a reminder that everything isn’t so bad.

It’s easy to overreact to failure, or try in vain to learn from it.

When I was a kid I thought raising the seat of a bicycle was a tedious process. Tools were still partly within the realm of adults, and carrying tools on a ride didn’t make sense to me.

So I took a pencil and a piece of paper and started designing a solution to that problem. It had been solved elsewhere. Nobody takes out a wrench every time they want to raise and lower their office chair. Instead office chairs are built with a hydraulic cylinder that can easily raise and lower, sometimes even while still remaining seated.

I didn’t have the skills necessary to make my idea come true, or even to see what could challenge its implementation, but I was using my imagination to try to solve a problem that was very real to me, and certainly to more people in the world.

This was an instance where my ambitions exceeded my abilities, but with maturity, some creative people learn to tame their ambitions and take on simpler problems.

For several summers while I was a teenager I worked as a summer intern in the factoring company my dad worked at in Paris’ Central Business District — known as “La Défense”. I’ve always been fascinated by skyscrappers and this was the only place in Paris where skycrappers are allowed to be built (that’s another story) so it was a great opportunity to make some money while being surrounded by cool stuff I could take pictures of.

Most summer interns for that company weren’t hired because of particular skills, so most of the tasks that were assigned to us were tedious filling tasks. Some enlightened employees did understand that they could benefit from our basic skills by letting us parse through smaller clients and actually lessen their current workload.

Over the course of several mornings I started noticing a strange ritual. Account managers whose specific task was to… manage accounts were spending up to 45 minutes routing external and internal mail that was deposited in a huge pile twice a day in the mail room.

People with a substantially higher salary than mailroom employees were doing the job of mailroom employees, for almost four hours a week, and seemingly for every individual department in the company.

This drove me nuts, and I didn’t even work there. It was repetitive, never-ending tedium that no one seemed to rebel against. Worse, each department had a copy/mail room with dozens of unlabelled racks.

The problem was there, in front of everyone, every day, and the solution was starring them in the face. In fit of “trouble making”, I spent an entire morning doing a census of all the employees on my floor, asked them the volume of mail they usually received every day (to gauge the rack space they might require) and tried to figure out how to designate any “catch-all” inboxes for mail without a specific receiver.

Better yet, I established an index of which companies belonged to which account manager to ensure that the mail people could figure out that an envelope with a “Sofradec” logo should go straight to Michel Denis.

I then printed labels in a very legible font (either Helvetica or the company’s slab font) and taped each rack in the mail room with the name of its rightful owner.

Reactions were a mix of boredom and amazement (yep…) and within a few days, the mail distribution rotations were reduced to a mere 5 minutes. I was elated, because I made people’s lives a little less repetitive. I don’t know if the system lasted, was replaced or improved upon later on.

As an outsider, I was able to spot the inefficiencies of that team very easily and provide an even easier fix that was completely painless to them. I don’t want to put all the blame on them for not figuring out something that simple earlier, it’s very easy to become stuck in tedium when it creeps up on you slowly.

This was a valuable lesson for me, now whenever I find myself acclimating to some inefficiency I have an allergic reaction against it and I do all I can to eliminate it. The most recent examples that come to mind:

• buying new trash cans for our office at Envy Labs because we were spending each day filling and emptying the shitty Ikea trash cans we bought when we first moved in
• buying a cheap plastic paper towel dispenser for our bathrooms because we were all ripping towels in pieces from the default metal dispenser
• grabbing a screwdriver to tighten the hinges of a door that was becoming increasingly difficult to open
• buying cheap Ikea lamps to use diffused lighting instead of bright overhead lights when working after sunset in the office, to prevent eyestrain that turns into headaches

Yes, many of these involve a purchase. Sometimes you can save a lot of time and frustration by investing a little money. You spend most of your life at work, make the best of it.

Most importantly, keep solving problems.

When is the last time you had a long hard day of work and tried to use your own product like someone who expects things to be easy after a though one?

When is the last time you got really angry because something didn’t work right when you finally had time to play with it?

The clarity such empathy can offer you is tremendous. You can find easy fixes, simple rewrites that will have a much more massive impact than some of the ambitious engineering and design projects you have underway.

All it takes is to stop building for a moment and experience the other side, and you just have to do that once in a while.

Associations in Rails 4 return a CollectionProxy instead of an Array. Calling a model’s association in Rails 4 might yield some surprises and unexpected breakage if you don’t take a careful look at what’s changed no difference whatsoever.

Considering two models with a has_and_belongs_to_many (HABTM) association to each other.

1
2
3
class Article < ActiveRecord::Base
  has_and_belongs_to_many :tags
end

1
2
3
class Tag < ActiveRecord::Base
  has_and_belongs_to_many :articles
end

Array vs. CollectionProxy

First, let’s create some records to play with.

1
2
3
4
5
tag = Tag.create(name: "Movie")
#<Tag id: 1, name: "Movie", created_at: "2012-11-02 06:18:29", updated_at: "2012-11-02 06:18:29">

article = Article.create(title: "Inception", tag: tag)
#<Article id: 1, title: "Inception", created_at: "2012-11-02 06:20:46", updated_at: "2012-11-02 06:20:46">

Now time to see how they behave differently.

In Rails 3.x

1
2
3
4
5
article.tags
=> [#<Tag id: 1, name: "Movie", created_at: "2012-11-02 06:18:29", updated_at: "2012-11-02 06:18:29">]

article.tags.class
=> Array

In Rails 4.0.0

1
2
3
4
5
article.tags
=> [#<Tag id: 1, name: "Movie", created_at: "2012-11-02 06:18:29", updated_at: "2012-11-02 06:18:29">]

article.tags.class
=> ActiveRecord::Associations::CollectionProxy

So far nothing too different, right? Sure it’s a different class but the output is the same.

Well, let’s add controllers and a basic JSON API. The console is a nice sandbox but I wonder how this new CollectionProxy works in the real world.

1
2
3
4
5
6
7
class TagsController < ApplicationController
  respond_to :json, :html

  def index
    @tags = Tag.all
  end
end

Nothing too fancy here, we’re only responding with JSON and trusting Rails to format the output for the index action of the tags controller.

Fetching /tags.json

In Rails 3.x

1
2
3
4
5
6
7
8
[
  {
    created_at: "2012-11-02T06:18:29-05:00",
    id: 1,
    name: "Movie",
    updated_at: "2012-11-02T06:18:29-05:00"
  }
]

In Rails 4.0.0

1
2
3
4
5
6
7
8
9
10
[
  {
    tag: {
      created_at: "2012-11-02T06:18:29-05:00",
      id: 1,
      name: "Movie",
      updated_at: "2012-11-02T06:18:29-05:00"
    }
  }
]

Alright, now the records being returned are surrounded by a tag object. Not really sure why it isn’t called tags instead since this is supposed to be a collection of tags, but let’s move on.

Update (2013-12-29): Yes, that’s because I’m using active_model_serializers instead of the Rails 4 default of jbuilder. Nothing else.

1
2
3
4
5
6
7
class ArticlesController < ApplicationController
  respond_to :json, :html
 
  def show
    respond_with @article = Article.find(params[:id])
  end
end

We built a simple show action of the articles controller.

Fetching /articles/1.json

In Rails 3.x

1
2
3
4
5
6
{
  created_at: "2012-11-02T00:57:19Z",
  title: "Billing thing",
  id: 1,
  updated_at: "2012-11-02T05:58:10Z"
}

In Rails 4.0.0

1
2
3
4
5
6
7
8
9
10
11
{
  model: {
    article: {
      id: 1,
      title: "Inception",
      created_at: "2012-11-02T06:20:46-05:00",
      updated_at: "2012-11-02T06:20:46-05:00"
    }
  },
  options: { }
}

Holy nesting Batman! Now instead of spitting out the attributes for the single record being fetched through the GET request, Rails active_model_serializers becomes a lot more specific. It reminds us that this record is a model called article and then prioritizes columns a little better. The ID makes sense at the top, then the data followed by the timestamps. I’m not certain what the options’ hash is supposed to contain but at first glance this seems like a cleaner default output.

As you can see, default JSON returns in Rails 4 are quite different from their Rails 3.x counterparts exactly the same unless you forget that you added a completely different JSON serialization gem like active_model_serializers. The formatting is better, but this is likely to require some work on whatever consumes your JSON API, for instance in some cases I either had to rewrite the JavaScript I was using to call my app’s API. In others, it made more sense (at least for now) to change this default output. Either on the fly using map or with JSON formatting tools like Jbuilder or rabl.

But you just wanted to be nice.

For many workers, the notion of being “in control” implies having what they consider urgent addressed right away. I’ve noticed this sort of regression to the mean in the way people tend to interact with their co-workers, whether they are hierarchically on the same level or not. People who were asked to do something, just got something done, or need to get something done will display the most callous behavior towards other people’s workflow simply because they can’t bear the thought of being stuck or not telling people — right now — about something they’ve just done.

“I need a minute of your time for this.”

“You need to take a look at this.”

“Just so you know, I took care of that thing for you.”

Shut up. Just. Shut. The. Fuck. Up. Your brain is grasping for reassurance, for feedback, and you’re not even noticing that you’re trampling on people in the process of trying to acquire that feedback.

You don’t” need a minute of their time for this, you probably need five or fifteen, but you don’t need them right now. You can leave them a note, an email — maybe even an instant message if you think it really warrants it — and they will get back to you at the optimal time for them. That time can be optimal for you as well, provided they don’t interrupt you callously while you’re in the middle of another task. But you assume that’s going to happen, because that’s just the way you would do it.

They don’t need to take a look at this. There’s no rush, unless you’re an EMT or a soldier. Nobody’s life is on the line. They can look at this later, on their own time, and get back to you with remarks if need be. Move on to your other task, drop this one off, keep moving. Quit controlling traffic.

They will know that you took care of “that thing” for them, eventually, it doesn’t need to be now. You do not need to tell them right away and feel be satisfied that they recognized how useful you were. They wouldn’t have asked you to do something for them in the first place if they didn’t think you were in fact helpful. You will get the satisfaction of them noticing on their own that you accomplished what they asked of you, and you will not prevent them from accomplishing something of their own in the process.

This may seem like a rant, but I sometimes wonder if these counter-intuitive notions can be taught to everyone. I have been the guy who constantly interrupts people for feedback and reassurance. It took a fair amount of listening and reading about people’s experience for me to notice that I was doing something wrong. Somehow, few people will complain directly to you when you’re breaking their flow. They will just accept it as the ransom of collaboration. It doesn’t need to be that way.

People can collaborate without asphyxiating each other. They can have parallel workflows without the constant need to collide.

This doesn’t mean that you shouldn’t ask questions, it simply means there is always a time and a place for questions to be raised, reassurance to be given, and thumbs to be shot in the air. Learn to respect other people’s flow.

I was taken aback by Liza Shulyayeva’s thoughtful blog post about coming to terms with the fact that since most people who surround her professionally are men, it’s likely that a large proportion of them harbor some sexual attraction to her.

She confesses that she didn’t come to terms with this because of any uncomfortable situation she directly had to face but simply because of someone whose opinion she values and who pointed it out.

Reading those lines is one of those moments. A moment like the one when a friend told me she had to plan her life around the absolute rule that she could never be alone walking somewhere at night.

Let that sink in for a moment. How often do you, as a man, wander about in the night from your office to a restaurant, or from a restaurant to a movie theather? How often do you think about your safety? Or the perception your loneliness projects on other people?

I’m sure you do think about your safety, you keep an eye out for your surroundings and the behavior of strangers around you, but on the whole as a man you can roam, freely. Now I invite you to consider for a moment, how you would consider a woman behaving as you do. Do you think it’s foolish? Irresponsible? Why do you? How can you possibly justify that if you value personal freedom?

Yes, reality is what it is. Men are often violent and abuse their average physical superiority over women in many ways, some discreet, others abject. But can you imagine having your life chained to that reality? Wouldn’t you revolt?

Let me come back to Liza’s premise, the emotional and physical attraction that seems impossible to avoid attracting when you are a woman in a world overwhelmingly dominated by men. While I’m certain there is a non-negligible proportion of men who simply want to enjoy the balance of power as it is, as a humanist and an optimist I like to think that people are often more vertuous than we like give them credit for. Ironically, this point of view is surely informed by a masculine bias.

My colleague Aimee Booth Simone was recently compelled to create a Meetup group called Central Florida Women in Tech and organize a Rails Bridge event dedicated to helping women learn to build web applications using Ruby on Rails. When she was in the early stages of organizing it she and I were talking about the rules of the event when it came to male students. She told me the only men allowed to participate were either teaching assistants or people accompanying women coming to the event. I found the rule interesting and asked her why she believed it had been established. Her answer boiled down to one feeling: comfort. It would be far less intimidating for women to get together in an environment where male-female interactions were essentially removed.

While this may sound drastic, I try to imagine if the situation were reversed. If a few geeky men were invited to join an large group of knowledgeable and often socially awkward women. While it’s easy to joke that men would hardly dislike the situation, in reality I doubt they would. The feeling of minority is never an easy one.

Now allow me to turn the tables on you.

Do you know why I came across Liza’s article? I was browsing Kickstarter for some of the comments left on the Try iOS campaign we recently launched. While doing so I noticed some positive comments, one of which attracted my attention more than the others.

Why? Because:

• it came from a woman who used the words “very happy to see this got funded”.
• it didn’t contain any typos
• the profile picture was quite attractive

So what did I do? I clicked on her name to learn more about her of course. Is that stalkerish? Maybe. I believe my curiosity isn’t unwarranted since any interest from women in technical matters is a boon to everybody. That said, I can’t deny that I wanted to learn more about her specifically, and not just “the person who was happy to see this funded”.

When I got to Liza’s profile page, here’s the order of things I noticed:

1. She had only backed one project on Kickstarter, ours. Proud.
2. She’s a web designer who likes JavaScript and AI. Cool.
3. She’s from Australia. Far. Awesome.
4. “Have superpowers. Can fly”. Quirky.
5. Her enlarged profile picture. Wow, she’s really cute.
6. Her website. Hmm.

Feeling curious I visited her website, because I wanted to know more about her, and wondered if her website would be interesting. When I got there I saw the title of her most recent blog post (“Male-female interaction and the thing that I just realized has been nagging at me”) and it hit me.

Like many passionate people working in an industry of passionate people, I was excited about the idea of finding someone from the opposite sex who could share that passion, someone that could even challenge me in that domain. Yes, it was directed by physical attraction and common interests. But, in the end, I struggle to think of a better way to define how anybody else on this planet finds people they want to maybe, perhaps, someday, if things work out, spend their time with and love.

It know this doesn’t make it easier to live surrounded by so many people whose longing is directed at so few of you, but hopefully my point of view will provide some women out there with a less gloomy perception on all this attention.

Upgrading Rails apps has become a lot easier over the years. Most of the time you can simply update your Gemfile, try to bundle and make sure all your existing Gems are compatible with the new version, if not run bundle update <gemname> on each of them one at a time until all dependencies resolve and then finally run rake rails:update, letting Rails make sure you’re setup properly for a new version.

The problem is that new versions of Rails often come with new default configrations inside of the following files and directories:

• config/application.rb
• config/environments/development.rb
• config/environments/production.rb
• config/initializers/
• Gemfile

And there’s always a lot to learn from those new default configuration. Even if we should, we don’t often catch all the subtle changes and improvements made to those Rails defaults. The result is that problems arising from upgrading to a new Rails version often come from not knowing about these new defaults.

To address this, Jacob Swanner had written a blog post for the Envy Labs blog last year offering useful Git diffs for the modified files between several different Betas and Release Candidates of Rails 3.1 and the 3.1.1 final release.

The Solution

Dwayne Henderson took it one step further by writting a useful Bash script that automated this process between a selected “old version” and the newest version of Rails available. Making it a lot less painless to get relevant information for the versions you care about.

Refining the Solution

His script didn’t really work on my system so I took it as an opportunity to improve it a bit and despite my serious illiteracy when it comes to Bash scripting, I came up with a version that:

• uses Bundler instead of RubyGems to create a version-specific skeleton Rails app, it’s much faster and doesn’t mess with your system Rubies or RVM Gemsets
• allows you to set which new_version of Rails you want to compare with the base_version
• if new_version is left blank it compares against the latest stable version of Rails
• provides descriptive colorized output for all actions being done by the script
• outputs the resulting Git diffs to your system’s default $EDITOR instead of less

true

Download the script here and make sure you save it as a rails_default_diff.sh.

Here’s an example diff from Rails 3.1.4 to 3.2.6.

Possible Improvements

I would love it if someone could help me test this script to make sure it works across environments and not just on my local machine, since I use ZSH and OS X I don’t know if this will act the same elsewhere.

Better yet, Jacob mentioned it would be a great idea to directly ping the Rails repo on GitHub for specific version tags to perform this without even needing to install new Rails versions locally. He’s working on a solution for that.

Finally, I think it would make sense to create a web service that outputs differences between blank slate Rails apps when you query it like this: site.org/from/v3.1.4/to/v3.2.6

My contention was that despite contrary claims made in some venues, there is no reason to be nostalgic of the good old days of Rails 1.x and 2.x. The simplicity of those early versions was far less joyful than rosy retrospection would have you remember, providing you do. Rails 3.0 and later version have introduced refinement, which can be confused with complexity but only on a superficial level.

Rails has always been about convention over configuration, and in order for conventions to be attained iteration and refinements must occur. Convention by its very nature implies a steeper learning curve, but its payback comes in the reusabibility of standardized knowledge.

My goal with this talk was to introduce newcomers to the Rails ecosystem by showing them some of the best development tools available. Another focus was trying to reassure people who come from Integrated Development Environments (IDEs) like Xcode, Eclipse or — dog forbid — Visual Studio and show them that a lightweight toolbelt can offer plenty of support for debugging, managing dependencies and a development environment.

Slides

Command Line Tools

I’ve gathered here some information and resources about the tools I introduced in this talk. Let’s start with some Unix tools that should be the foundation of your development environment.

Homebrew

Homebrew is the best package manager for the OS X ecosystem.

A package manager is tool that does several key things for you:

1. Resolve dependencies for the piece of software you’re trying to install.
2. Download each piece of software’s source code.
3. Configure the source to be compatible with your system.
4. Compile the source into an executable binary program.
5. Allow you to upgrade any of these binaries very easily.

That’s a lot of stuff right there. Things that you don’t have to worry about when installing something from a disk image (.dmg files) or from the Mac App Store since those are already compiled into executable programs for you.

You might (and should) ask: why not download pre-compiled executables instead of their source code? For several programs, Git for instance, you can actually do that by going to Git’s official website and hit the download section.

For many other programs, it’s not that easy. There are intricate interractions with other programs on your system that need to be accounted for before an executable version can be created and function properly on your system. Just to be clear, an executable is a program that can be launched, an application in modern parlance. The source code of a Unix program can’t be executed before that program has been compiled, that’s just the way it is.

Now if you’ve been doing development on a Mac for a while, you might have heard of MacPorts. It’s also a package manager which was a predecessor to Homebrew and up until a few years ago was used by a majority. The reason a majority of developers have moved on to using Homebrew are multiple.

For one, MacPorts used convoluted ways to install programs since it didn’t use several libraries and software already available on OS X which resulted in slow installation and complex dependencies. Complexity is something people shy away with in this realm because having many moving parts is often a recipe for issues.

Homebrew takes a simpler and more lightweight approach. While at first it didn’t offer as many installation recipes (or formulaes in Homebrew-speak) as MacPorts, the fact that formulaes are written in simple Ruby allowed the stable of programs it was capable of installing to grow at a fast rate. So much that it’s hard to find anything that you can’t install with Homebrew.

I mentioned several of the popular packages available through Homebrew in a previous post called Brewing with Homebrew. You’ll also find instructions on how to install it there.

If you had been using MacPorts for a while, Moving from MacPorts is a great article that more reasons to switch and simple instructions on how to do so.

AutoJump

A great little utility that remembers folders you’ve cd-ed into and allows you to “jump” to them from anywhere simply by typing j <foldername>. For instance, once I’ve done cd ~/Development/envylabs/codeschool/ once, I can just type in j code and it will take me straight there. j c will also work until you cd into another folder that starts with a C, at which point you’ll have to be a little more specific. It’s extremely useful once you start navigating around many different folders and files on the command line. It feels like using Spotlight, Quicksilver or Alfred on the Terminal.

Ruby Gems

Here’s a quick breakdown of the interesting gems I mention in this talk. All of them offer command line interfaces (or CLIs) which allow you to interact directly with them from the command line and send them commands.

RVM

RVM has been for years the only way to manage multiple versions of Ruby on a single development machine, and before the advent of Bundler with Rails 3, it also served as a way to prevent collisions between gems (Ruby libraries) installed on your system. Its relevance has nowadays been lessened by the more simple rbenv and the bundle exec command offered by Bundler, but it’s still a good choice for beginners.

If you’re not a fan of managing Ruby versions and Gemsets through the command line on a daily basis (you shouldn’t if you’re using .rvmrc files, but nobody’s perfect) you should take a look at JewelryBox, a free graphical user interface for RVM for OS X.

Pow

Once you start working with more than a single Rails application and you need to run more than one at the same time it can become tedious to start a web server for each using the rails server command every time. It also means you have to start assigning ports to each server to prevent collisions.

Pow is a simple little tool built by the 37signals team that allows you to assign a made-up domain name to each of your apps. Whenever you enter that domain name in your favorite browser, Pow will start a Rails server for you and launch the app in your browser. Not only is it convenient, it can become crucial when you’re building two apps that depend on one another to function.

Better yet, in this world of powerful little tools, another Gem called powder provides you with an interface to install and manage all your Pow servers. It gives you convenient commands to create specific domain names for a given app, watch its development log, and restart it.

There’s an inherent issue with Pow that causes it to stop working once an Internet connection isn’t available for your machine, and sure enough powder solves that with a convenient command called powder host. This will add all your Pow application domain names to your system’s host file, which is where your system ends up looking when no Domain Name Server (or DNS) is available on the Internet. And now you can use Pow on your next plane ride!

Pry

Debugging is something many people coming from Integrated Development Environments (IDEs) worry about when coming into the Rails ecosystem. Setting break points to inspect code at a specific point within a program is a common and very straightforward way of figuring out why something isn’t working the way you expect it to.

Sadly the most popular debugging tool for Ruby and Rails, ruby-debug19, hasn’t been updated since 2009. An eternity for a vibrant open source community like Rails.

Pry offers a slightly different approach to debugging by offering an interface similar to the classical Unix command line. When stepping through a program frozen by a break point, Pry lets you cd into objects and classes to inspect their properties and methods the way you would inside of a directory structure. It’s literarly like code spelunking, which somehow makes debugging a more concrete experience.

Pry has several other great features that for instance allow you to jump the line of source code your currently debugging within your favorite editor to fix a bug in place. It also has several extensions like:

• pry-nav which allows you to resume execution your program line by line and even step backwards
• pry-stack_explorer which lets you climb inside the call stack, examine the state of each frame of the stack and even evaluate code in there.
• pry-remote goes hand in hand with Pow since unlike the traditional Webrick or Thin web servers launched through the rails server command, you can’t add a breakpoint and interact directly with Pry when using Pow since it’s running remotely. Pry Remote offers you a new binding.remote_pry statement that will interrupt the execution of the Pow server and wait for a client to connect to the debugging session. You’ll then just have to run pry-remote from any command line on your system and you will be taken into the usual Pry session, minus the pretty colors.

You can find more great information about the Pry Ecosystem in this excellent blog post.

Bundler

Hard to overstate how amazing Bundler has made working with myriads of gems with different version dependencies inside of an application. This used to be hell for developers, hence the usefulness of segragated Gemsets through RVM.

Thankfully Bundler offers the bundle exec command which will run whatever command you pass it bundle exec rake db:migrate for instance with the version of rake it resolved as compatible with the Gems declared in your Gemfile.

It’s a bit complex to understand. To summerize, you may have installed and activated version 0.9.2.2 while your Gemfile.lock — the file Bundler creates once it has resolved all the cross-dependencies of all the Gem versions in your Gemfile — requires version 0.9.1 to be used. Since you don’t have version 0.9.1 anymore — you’ve upgraded — you need to tell Bundler to point to rake 0.9.1 instead, which it does through bundle exec rake.

You can verify that by running rake --version and bundle exec rake --version in a project whose Gemfile requires an older version of rake. The two versions should be different.

Semantic Versioning & Loose Version Dependency

Semantic Versioning is a concept that tries to hold developers to meaningful versioning of their software.

A major version (1.0.0, 2.0.0) should be expected to introduce major non-backward compatible changes. A minor version (1.1.0, 2.1.0) should be expected to introduce minor non-backward compatible changes. And finally, a patch version (1.1.1, 2.0.1) should only contain backward compatible bug fixes.

This is a simplified explanation of the more nuanced explanations and rules covered at semver.org but it should give you an idea.

Now loose version dependency is a practice whereby declaring gem dependencies in your Gemfile, you don’t specify a safer specific version (gem "rails", "3.2.2"), or a much more dangerous minimal version (gem "rails", ">=3.2.2") but instead make the version dependency loose: gem "rails", "~> 3.2.2".

With this notation. Bundler will automatically try to update the Rails gem if it finds a newer version than 3.2.2 but will never upgrade to version 3.3.0, which would be a more unpredictable non-backward compatible minor version bump by the definition of semantic versioning. This notation only tries to update the latest number declared, so the much less safe gem "rails", "~>3.2" can also be used, but isn’t recommended.

More Tools

That’s about it for this long foray into the constellation of open source tools available for Rails development. Here are a few excellent resources available to find more:

• ruby-toolbox.com
• rubygems.com
• railscasts.com

And if you’re a Code School subscriber, we regularly release Code TV screencasts on various useful tools and libraries for Ruby and Rails development, I can’t recommend them enough.

That seems rather contrived but screwing up is not a small matter when it comes to learning. Our inhibitions as human beings make us go to great length to avoid failure. Few people associate it with a positive experience. And if you think back to your experiences at school (good luck if you’re still going through it), try to picture the number of times you had an answer to a question posed by one of your teachers but sat in silence for fear of getting it wrong.

You didn’t learn that day. You wasted that opportunity because the fear of embarassment was greater than your self-confidence.

Now what if your initial exposure to new information was made in a context in which social pressures were taken out of the equation? What if you were shown concepts and asked questions about them in a shame vacuum?

That’s precisely what can make practicing through interactive challenges such a fertile ground for growth-inducing failure. For instance, most of our students at Code School put in dozens of attempts before they even consider asking for a hint.

They’re far more active towards their learning experience than I would wager the majority of High School and College students are towards the lectures and labs their participate in.

As shown by this excellent Wired article and the studies it presents, a student’s mindset towards failure can have a dramatic influence on how well they learn. If we can foster an environment where students only care about disappointing themselves when they screw up, I think we’re on the right track. And it may even catch on in the classroom.

“Most people never pick up the phone, most people never ask. And that’s what separates, sometimes, the people that do things from the people that just dream about them. You gotta act. And you gotta be willing to fail… if you’re afraid of failing, you won’t get very far.” — Steve Jobs

What if we’re wrong?

What if Bret is right and the red, green, refactor isn’t a feedback loop that promotes creativity and discovery? Sure, it’s fast. It’s iterative and it gives us a suite of clearly defined assumptions to rely on in order to gauge the stability of the programs we’re building.

But what if such a science-based programming — as I like to think of it — is sacrificing an essential component of the process of building?

I recognize that as someone who begun as a designer I have a tendency to regress to that mean. The one of experimentation, trial and error. The one of repeated fumbles and smudges that with perseverance can turn into a great thing. That’s how I instinctively want to write my code even though I know that I’m not skilled or controlled enough to be trusted without the safety net provided by testing.

Another way

Or maybe the kind of programming that Bret presents through his innovative development environment is just one other way to code. A way more suited for creating visual output, animations, interfaces. Maybe that’s where the front-end development community will gravitate toward. Come to think of it, it would make a lot of sense.

It’s difficult for me to resist the appeal of a human and feedback-friendly interface. I believe the feedback loop is something too many creators neglect. A sanity check where sanity equates to reality and can take developers back down to the ground when they get lost in abstractions.

Having spent a good part of the afternoon toying with Guard and its various extensions I realize that this kind of fast and tangible output is something I have been craving for.

Seeds

The first time I ever heard of Envy was through a young social game called Gowalla. I lived in East Orlando at the time and since very few spots had been “created” in the area, I took it upon myself to correct that, hoping that it would allow me to amass riches of badges, icons and other virtual carrots.

There were a few people I regularly saw in the list of recently checked-in at some popular spots in the area, and then there was Gregg Pollack. With his double set of double consonants, this guy seemed to be everywhere. I discovered by snooping his profile that he was in possession of badges (or pins) I had never heard of before. One of them — “Code Monkey” — was awarded to people who had checked in at an impressive amount of startups or tech company headquarters. Color me intrigued and envious.

One click on the URL listed under his profile and I discovered a colorful website with tons of personality describing a then young web development consultancy. From what I could gather, these guys were actually from Orlando. I was impressed. I had no idea – at the time – that there even was the semblance of a serious tech scene in central Florida, let alone Orlando.

Happenstance

A few months passed and after thousands of drive-by checkins and an ever increasing addiction to Gowalla and the virtual copies of Zeldman & Vaynerchuk books it awarded me, I found myself in Miami for the Future of Web Apps conference put on by Carsonified. While I was strolling around with friends from Full Sail trying to creep up on Dan Benjamin — whose 5by5 network was barely blossoming at the time — I noticed a bunch of guys sitting nearby. One of them looked a little too much like my Gowalla Nemesis for it to be a coincidence, and I therefore decided to introduce myself to him by using that very moniker:

“Hi, I believe you’re my nemesis on Gowalla…”.

He looked at me like I was insane for a second, paused, and then giggled after — I assume — remembering that he had seen my mug around East Orlando’s Gowalla Elite as well. I doubt Gregg realized it at the time, but I had been trying to break the ice with some of the shut-in types at the conference for a while, with very little success until then. And while I was still glowing in the satisfaction of my ballsy self-introduction, I forgot to foresee that this was to be one of the key moments of my life.

The conference went on, things were learned, bladders were maimed, and deep conversations were exchanged on the invaded roof lounge of an overly loud South Beach bar. I then came back to Orlando and failed an introduction to programming class for the second time because I chose much needed sleep over cramming for the following day’s final exam. And even that proved worthwhile.

Opportunity

BarCamp Orlando was scheduled several weeks later and Gregg was interested in getting some Full Sail students to attend so we met over lunch to discuss that and he gave us – cleverCode, a little company I had co-founded with my friend Zach Nicoll from Full Sail – the opportunity to revamp a site called Ruby Heroes which had been used the previous year to reward the unsung contributors of the Ruby community at RailsConf. More surprisingly, he offered to pay us, bringing our contingent of paid clients to the whooping number of two. We did a pretty good job for the amount of skills we had at the time and kept in touch over the following year, collaborating on another project with cleverCode later that year.

Ruby Heroes was the first Rails project I ever participated in, as a web designer at the time. I had very little experience with back-end development and even front-end development. When Envy Labs presented the first version of Rails for Zombies in August or September of 2010, I jumped on the occasion to start learning Rails inside and out since the Ruby and Rails community had impressed me deeply with design standards that were much higher than most developer-centric communities I had encountered. But there was something deeper than that. Through a collective focus on educating new users, practicing test-driven development, allowing fast iteration through simple library dependency management, there was just something more sane and thoughtful about that community.

This comes from a science-minded skeptical guy. I had been weary of joining groups and clubs for years and my strong opinions on design and user experience often put me at odds with developers and engineers who often forgot about human beings and ended up caring more about the systems they built than the people they were building them for.

Envious

The group of people that makes up Envy Labs represents to me some of the finest qualities you can look for in builders. Despite my early reservations regarding Code School’s potential, they have regularly impressed me by not just doing what’s sufficient, but what’s best. Screencasts are nice, you can be introduced to a high quantity of concepts in a short amount of time. Practice is better because it’s the only true way to hone in a skill. The problem is that while screencasts get you pumped up about a specific topic, there are always good excuses to delay the practice of those newly acquired concepts. Code School meshed those together in a very successful way, honoring its “Learn by Doing” motto. Doing it this way wasn’t the easy way.

Coming from a school like Full Sail, where instructors and course directors are encouraged to practice freelance work in order to maintain their proficiency in modern development skills, an environment like Code School seems like a perfect transition. Full-time designers and developers, some of the best in their field, regularly churning out dense educational content for people who already are in the web industry with some basic knowledge, but who are looking to discover the best practices and techniques used by thoughtful craftspeople.

The working environment at Envy Labs is unlike anything I’ve ever imagined before I joined the web world a few years ago. I’m familiar with the well documented excesses of trendy startups, but this is no startup. It’s a profitable business that was gradually built on hard work. And it focuses on being the best place for a developer or designer to work in — or out.

What this environment results in is some of the best work I feel I’ve ever produced. And I’m saying that after a mere four weeks where I haven’t produced that many significant things. But a good team isn’t necessarily defined by the complete things you work on individually, it’s defined by the cumulative efforts of people who feel the confidence of deeply investing themselves into what they do. It’s not that easy to trust that if you raise your hand to say something isn’t right, somebody will listen and agree to let you fix it. And when this someone responds by fixing that problem themselves because they recognize the value of what you brought up, there is no better token of trust and respect. Which in turns motivates you to pay it forward.

I could fill pages with the thoughtful and enlightening conversations I’ve had with Thomas, Nate, Chris, Dray, Eric, Gregg, Adam, Aimee, Drew, Mark, Josh, Nick, Violette, Caike, Jennifer, Jason, Matt, Jacob, Tim and Adam.

And it’s only been four weeks. I can’t wait to write about the next forty.

In Sublime, the utility is hidden in the application package, and assuming you installed Sublime in /Applications you can check that it’s available on your system by running the commands below:

1
2
cd /Applications/Sublime\ Text\ 2.app/Contents/SharedSupport/bin/
ls

The only thing you should see displayed is subl. If not, go install the latest version.

You can find more (official) documentation here.

Installation

Note: These instructions assume you’re using the Terminal app out of the box, without ZSH or any fancy prompts like that. I trust you will be able to adapt these instructions yourself if you do.

The official documentation I linked to above recommends creating a ~/bin folder (in your home directory). That’s weird, I don’t recall ever being asked to do that on OS X since most people install binaries within /usr/local/bin which – if you’re a developer – is likely to already have tons of other binaries.

So let’s stay within the OS X conventions by doing:

1
ln -s /Applications/Sublime\ Text\ 2.app/Contents/SharedSupport/bin/subl /usr/local/bin/sublime

This will simply create a symlink called sublime (remember, we like names that don’t suck to type 500 times a day) between the subl binary stashed in the Sublime application package, and a folder where your system usually looks for binaries to execute (launch). Think of it as a wormhole of awesome.

Now let’s do a check to see if everything will run smoothly. Enter this:

1
open ~/.bash_profile`

You should see at the top of the file a line that starts with: export PATH=

This contains all the directories that will be looked into for executable binaries when you type a command in Terminal. Since we create a symlink to subl called sublime in the /usr/local/bin directory let’s check if this directory is listed on that same line.

If it is, perfect. Let’s keep going. If not, simply add it like this and save the file:

1
export PATH=/usr/local/bin:(...)

Note: The “(…)” in this example represents other folders that would be listed on the same line and separated by a colon.

If you had to add /usr/local/bin to your PATH, run the following command before continuing:

1
source ~/.bash_profile

This will reload your .bash_profile with the newly added directory.

Testing

Open a Terminal window and run:

1
2
# replace <filename> by an actual file name
sublime <filename>

or

1
2
# replace "foldername" by an actual folder name
sublime <foldername>

or even

1
2
# to open the entire current directory
sublime .

Conclusion

Now you don’t need to get out of Terminal to simply open a file or a folder, you didn’t have to add an “alias” or yet another bin directory to your .bash_profile which you would been have needed with the official instructions given by the Sublime team.

Have fun, Sublime is a great editor showing a lot of promise and you should check out the recent beta release.

One my first website ever, which I built in 1999 with Microsoft Front Page, I decided to have on the left side a menu that listed each page. There’s a good chance my brain is constructing this memory but I think that the first time around I only had two or three pages, so I simply copied and pasted the same list of links on each.

It surely looked like this abberation:

1
2
3
4
<P><A HREF=page1.htm>- Page 1</A><BR><BR>
<A HREF=page2.htm>- Page 2</A><BR><BR>
<A HREF=page3.htm>- Page 3</A><BR><BR>
</P>

This is atrocious code, please don’t ever use this.

Then after I had organized everything so neatly I thought about adding a fourth page. Boy, the agony. Imagine that. I had to open every single one of those (three) files and add a new link to <A HREF=page4.html>-Page 4</A><BR><BR>. With my then collosal experience in web mastery, I could not stand for this. I had to find a way to make this more efficient.

Oh, hi! This is a reality break. Efficiency as described in the paragraph above is nothing else than pure and utter laziness. There’s no way around it. But you know what? Laziness is the mother of all invention. If less people settled for repetitive crap, you can bet we would already have our flying cars. So don’t settle, you’re making me wait for the future, and I don’t like that.

So, back to efficiency. How do you achieve that kind of feat in HTML 4.01 when Internet Explorer 5 was on the cutting edge of browser technology?

1
2
3
4
5
6
7
8
<FRAMESET ROWS="15%,*">
   <FRAME SRC="title.html" NAME=TITLE SCROLLING=NO>

   <FRAMESET COLS="20%,80%">
      <FRAME SRC="menu.html" NAME=SIDEBAR>
      <FRAME SRC="page1.html" NAME=MAIN>
   </FRAMESET>
</FRAMESET>

You guessed it! Frames! Perfect. Until you actually open than in a browser.

Even for my highly tolerant (I used Papyrus and thought it looked awesome) 1999 self, this kind of thing was just too ugly to live. So I tried to find a better way.

Server-side seduction

I didn’t have any idea at the time, but it turns out my ideal solution involved using the server. Something I had never heard of outside of a restaurant. I could ask my little server guy to include the menu page of my site for me everywhere I wanted it and it could do it by simply injecting the content of the menu.html file wherever I put the following code:

1
<!--#include virtual="header.html" -->

I then needed to rename all of my existing pages to a .shtml extension for this decidedly not so smart server to understand that I wanted what looks like an HTML comment to act like an order: “Include this file right here, Mr Server man. No, I will not tip you, you didn’t bring me any food.”.

I soon discovered a thing know as PHP could allow me to do a lot more nifty things like this if I found a server which knew whatever that acronym meant and enjoyed bad phpuns about elephants.

So now I could do things like:

1
<?php require("menu.html") ?>

That little trick would reward me with a nasty error if by any chance my menu.html file was missing and stop loading my page altogether until the issue was addressed and all was right again in the world. And that was about the extent of my PHP knowledge for several months after that. I remember seeing echo() statements here and there and a few MySQL query examples but I didn’t get into fiddling with server-side programming until a few months and years later when I found a guy crazy enough to build a back-end system for one of my websites.

Stay hungry, stay DRY.

That’s the end of that trip down memory lane but I want to underline the interesting part here. Despite a total lack of technical knowledge, it’s my laziness and drive for efficiency that eventually led me down the slow path of acquiring enough skills to repeating myself less with websites, eventually evolving to dynamic websites, discussion boards, and database storage.

Between this first bit of awful HTML code and now, there are 13 years of tinkering, curiosity, foolish explorations and long night of frustration and pleasure. So the next time you find yourself doing a repetitive task, stop for a moment and explore the web to see if you can find a way to do it the smarter way. You might end up a Web Developer a few years down the line, or you might simply save yourself a good chunk of time and learn some cool things along the way.

“Is is better to know or not to know?”

I think this is a fundamental question that is often ignored or brushed off by both the pro-science and the anti-science factions.

There is a certain beauty in ignorance that I can’t ignore, even as a science lover. But I think what I define as beauty is very different from reveling in the “mysterious ways” of the universe. I don’t like mystery. What I like is imagination.

Yesterday I was looking at an automatic pool vacuum cleaner — at least I think it uses vacuum — wondering once again how the hell this thing was making its way across the bottom of the pool. I don’t know how it moves, how it cleans, or what it is able to clean. Yet there I was staring at this thing having short spasms and trying to imagine what mechanism could possibly make it function.

On my own, I wasn’t able to come up with a satisfying answer. That, in my mind, creates something very similar to a vacuum, or a gap. That gap needs to be filled or I will be frustrated every time I see this thing again. It will remind me of my laziness and lack of will to inquire about it and find some kind of definitive answer. It prevents me from moving on to hunting another mystery.

I can’t deny that when I finally find the answer to how it works (and I plan to do that, soon after I publish this) I will be satisfied. Yet as someone who prides himself in understanding the world around him, I will have a slight disappointment that I could not predict how it works before I looked up the answer.

Not knowing also provided me with a catalyst for my imagination, which I believe is one of the greatest reasons why people dislike science. Science is there to confirm one hypothesis, and deny all the others any legitimacy. It feels unfair, because your pet theory wasn’t chosen to be the truth. But that’s not at all what it is. No one decides or chooses truth, it just is. All you have to do is be willing to discover it.

So to answer the question I posed as a title, yes, it is better to know. It’s sometimes unsettling, surprising and it can be frightening. But those adjectives can be taken to describes some of the most wonderful things about life. Sheltering oneself from knowledge isn’t nearly as satisfying as gathering the abilities to discover knowledge on your own. The excitement, the joy of discovering are far greater than the comfort of imagining.

And no, it doesn’t take the poetry out of the world, because there are always bigger mysteries to discover.

My initial question

Alan – nicest guy in the world & very talented lead developer of Treehouse was the first to opine:

Alan 1 Alan 2 Cory 1

I then asked a follow-up.

Follow-up

Alan 3 Alan 4

Speaking of talented fellas, Nick – a web designer at Envy Labs who worked on Code School and the fabulous Why-flavored redesign of TryRuby.org – answered:

Nick 1 Cory 2

Ryan – a swell guy from NY, designologist, co-founder and web designer at Think Bigr – replied:

Ryan 1

Last but not least, Mark – a terrific web designer at Shopify, said:

Mark 1

To conclude almost every single response presented an approach where styles are written in a standards-compliant environment (today that would be Chrome or Safari, more so than Firefox) then adjusted for IE’s obsolete ways.

Keep this in mind, because a production process tied by IE-compatibility from the get-go is likely to create frustrations and creative limitations very early on. It doesn’t mean one shouldn’t consider IE before the end-stages of a project (as Nick pointed out, the demographic matters a lot) but be weary of efforts towards graceful degradation that may be rendered unnecessary by late design decisions.

Project managers are rarely as cautious with CSS since it doesn’t directly impact business logic (back-end), which means they are more likely to propose modifications to styles later on in a project than they would with controller-logic that could cause functionality breakage.

Managers also often expect websites to look the same in every browser. If you catch any flak when adopting such a process, don’t hesitate to point out that many web professionals adopt a similar technique because it is the most efficient use of their time. Going and back and forth between standard CSS and IE fallbacks after each design iteration is a waste of your time and their money.

If managers or clients somehow insist of having fully IE compatible sites after each iteration, several people have suggested introducing an IE tax to give everyone a clear picture of the true cost of obsolete browsers on development schedules.

I highly recommend Andy Clarke’s thorough breakdown of his Canny Bill redesign across progressively less advanced browsers and his benchmark browser approach.

Finally, one of the best tools to further the cause of graceful degradation (a much more logical moniker than “progressive enhancement”) is Modernizr, spearheaded by Faruk Ateş, Paul Irish and Alex Sexton.

I was stuck by the careful details Phil Schiller went into just to describe how this camera was made, why it was made and exactly why it was so good.

And then he said this:

I’ll end it with this one – I could go on and on, but I’ll end it here. This is a nice begining of evening shot. You see a little bit of depth of field, right? You’ve seen that in a couple of these photos. The background’s blurred because that aperture 2.4 allows us a little depth of field. And you get just want you want in a sunset photo, the start of that salmon color that the sun makes. A bad auto white balance setting would make this sort of a neutral grey and ruin the beautiful color but not the iPhone 4S.

This is just one of many details aimed at people who know this stuff – and with my short experience as an amateur photographer and camera salesman, I think I do. One of my favorite conversations with customers at the electronics store I worked at in Paris was the “Megapixel Conspiracy”. Most would-be photographers would come to me as the approachable long-haired 23-year old and ask me which camera had the highest pixel count.

These people were not stupid, despite what many cynical salespeople will have you believe. Pixel density in a digital camera sensor is one of the few quantifiable things about these gizmos that normal people can grasp at a glance and use to differentiate them. The digital camera industry never did anything to dispell those misconceptions, it even stamped the pixel counts on the cases of each camera as if it were even more relevant than maximum aperture – it’s not.

Phil does in this short segment what I would have had to do with customers who seemed receptive to my advice: explain to them that cramming pixels in a camera sensor makes for bad photos, not good ones. And granted, this knowledge is a little more widely spread these days than just a few years ago, but since the iPhone’s inception in 2007 this litany of pixel count inferiority has been the rallying cry of clueless competitors.

It used to be Nokia and its atrocious N95 (possibly the worst phone camera I have ever seen). Nowadays it’s Motorola, HTC and the like with their humongous screens that can barely be operated one-handed and with cameras boasting feature-checklist-friendly megapixel counts.

Guess why the iPhone is beating some worthy DSLR rivals in photo sharing site popularity?

1. despite some obvious shortcomings, iPhone shots don’t look like ass.
2. iPhone users actually use their cameras, and they have an easy path to sharing them.

To finish off, here are some of the thoughtful details mentioned by Schiller: group facial exposure, lack of barrel distortion, shot-to-shot time, time-to-photo, depth of field, wide aperture, large dynamic range, accurate skin tones, etc.

I don’t know if Schiller is a camera enthusiast himself – it sure sounds that way – but at least this small presentation of the iPhone 4S’ visual chops reassures me that whoever is in charge of iPhone photography knows what they’re talking about.

I’ve owned a Canon EOS 5D Mark II for 2 years now. I bought it on a whim with money I should have saved for tuition in college. I made some of the technically best shots in my life with it, yet I have consistently made better and more memorable photos with my iPhone.

Why? Because it’s always there and it can take almost anything I throw at it. I’m thinking about selling my Mark II shortly after I receive my 4S.

“Do you know how hard it is to get a squirrel to stand still? Not easy.”

PS: You can find actual shots (full size original files) from the 4S on Apple’s website.

I had last seen my grandfather in a small hospital not far from where he lived with my grandmother in a very rural part of central France. I say that I saw him but in truth what I saw wasn’t anything like him, his eyes were lost, he had lost a considerable amount of weight for a man who never seemed to have an ounce of fat on his bones.

He used to be tall and proud. He was a working man. He was a farmer and a wood carver.

When the phone rang and my mom told me that her dad had died, she sounded broken. That got to me even more than the news did. She’s an anchor, and she was loose.

I don’t know whether it was a concern for ruining everyone’s day or the fact that I was stunned, but it seemed like I felt nothing when I hung up the phone. My friends asked me about the call and I misdirected to avoid telling them what had happened. It was time for us to leave and I was the driver. I decided to go to the bathroom. I opened the door, intent on actually using the bathroom. I closed the door, sat down. Facing me was a mirror projecting my face. In it I saw my mom’s pain and despair. I started crying uncontrollably. I was losing it. I turned on the restroom fan to cover the sound of my whimpers and I stared myself blank in the eye.

I let the pain take its stab at me. I thought about my grandma and the loneliness she would now have to face living in a hamlet with a population of less than 20. She didn’t know how to drive, only he did. She lost her anchor too.

Yesterday, I left work frustrated over something trivial. It had mostly been a good day, but that little thing angered me enough that I needed some fresh air and stimulating company. I drove to my alma mater and sent a few messages around to see if any of my old classmates who currently work in the Web degree there were on campus.

Adam replied, we had dinner together and talked about my frustration, his fruitful discovery of Ruby on Rails, and he told me he was in charge of a lab at 9PM. I told him I would stick around until then.

After dinner we got back to the faculty offices, he went away for a second and I went to see if some of my favorite instructors and mentors were in the office. I was hoping Edward Almeida – who’s in charge in Final Projects – would be there. He was. I could see light emanating from his desk. I put my head above the separator of his workspace and made a silly joke about being “ahead”. He didn’t smile, he looked weary. He nodded toward his computer screen.

Black on white, the words read:

1
Steve Jobs   1955 – 2011

“Fuck me.”, I uttered, and walked away.

Adam came back and asked me if I had heard. I said yes, and made some banal comment about the night being ruined.

Then without agreeing to it, we fell silent. Some people around the office discovered the news in the minutes that followed and were in disbelief. I saw a message from my friend Andrew telling me he was crying and his mother didn’t understand why. It was his birthday.

As I am now, I told him I was holding back tears. I felt an overwhelming need for privacy and headed to the office restrooms. I locked the door, sat down, and let the pain have at it once again.

That summer when my grandpa died I bought my first Mac, it was a refurbished MacBook Pro I ordered for a little cheaper online. Half of me had been swayed by the first iPod I bought in 2006 at the 5th Avenue Apple Store in New York City with my friend Clément. The other half wanted to prove all those Mac jerks wrong. I also felt I was at a turning point in my life. I was done with college in Paris and I harbored the foolish hope that I could find a good excuse to work or study in Florida, with which I fell in love the year before.

I was using computers regularly before I was even 10 years old. In 1995 that was still a huge deal, no one at my school owned a computer. My dad bought a beige Compaq anvil for Christmas, sometime before 1994. Since then every computer we had owned was powered by a Microsoft operating system.

We were tinkerers, we made our own machines. Despite the fact that they barely ever worked properly, we were proud of that. I regularly laughed at and had arguments with Mac owners during my teenage years when I became an amateur web designer. They were overly expensive, slower than cheaper Windows machines.

Somewere along the line we didn’t realize that what most of those weird Mac people were saying was that they loved their computers. We didn’t. We hated our computers. Despised them for crashing constantly and being the antithesis of what a tool should be. Tools should help us make things.

Since that summer of 2008, I’ve been a proud Mac owner. I own a professional DSLR camera, yet my favorite camera is my iPhone. Most importantly, at the begining of 2009 I moved to the US to design and build things I love. I took the reins. I would not have enrolled to Full Sail University and left my friends and family 7000 kilometers away if it weren’t for these words.

Yesterday I lost another anchor.

Morning

Get back into context

• What were you working on yesterday?
• Is it finished? What’s left to do?
• What should you do today?
• Are you in anybody’s way? Is someone in your way?

Find the flow

Mornings are one of the few quiet moments in an office, and in life in general. Take advantage of that. Start slow, make sure no one can or should break your rythm for at least 1 or 2 hours.

Stand on the summit, look around

Once you hammered out some of the most productive work of the day, take a break when no more critical loose threads are hanging.

Noon

Hunger is the enemy of focus

As soon as you feel the growlies take over, try to find a way to slide a bookmark into your flow. Make sure you leave off a not too steep path back to the summit. Your satiated self is a lazy beast.

Don’t put your digestive system into overdrive

There’s a reason we have sandwhiches, salads and other reasonably-sized portions. Light meals don’t sit in the belly for hours, reminding you that your digestive system always calls your brain to say that you’re full 10 minutes too late.

Make sure no urgent matter is ignored

Notice, I didn’t tell you to check your emails this morning? There’s a reason: so you can focus on your work when you can do it best.

That said, it’s best not to ignore urgent stuff altogether. The afternoon is a better time to react to unplanned events. You can get back to people before the end of the day, and that’s fine.

Afternoon

Don’t resist distractions

People assume creativity dwells in quiet times, that it officiates only in early mornings and late evenings. That’s a misconception. Creatitity never sleeps. It lurks there all the time, especially when you’re not conscious of it.

Distractions are fertile ground for creative thoughts, they are essential breaths, punctuations that allow meaning to emerge from a misty problem you have been trying to evaporate.

You can’t replace distractions with work, they can’t be converted, they’re not using the same cognitive encoding. Regardless, fighting human nature is often a bad idea. You think you have it under control until it rebels against you, it’s a smarter bet to live in harmony with it.

If you can’t finish today, there’s always tomorrow

Nothing should ever make you feel compelled to stay all night at the office. Being on tilt isn’t productive, it’s self-destructive.

That’s not to say you can’t be on a roll, but you have to remember that you can’t always finish everything. And in environment when you make productive time less of an exception, it shouldn’t be hard to get back on a roll.

Sustain momentum

You can run as fast as you want, you will always need to draw breath. It’s going to catch up to you.

Run steady, stop to rest. You’ll get there fast enough, and you’ll be ready to keep going instead of lying on the floor, a sweaty mess.

Note: I intend on updating this article with any useful feedback, so don’t hesitate to provide some to me on Twitter. It was inspired by my own thoughts on productivity, as well as the works of Merlin Mann, Jason Fried and David Heinemeier Hansson.

Homebrew is the best package manager available for Mac. If you’ve heard of MacPorts, I strongly urge you to consider switching to it.

If the concept of a package manager is foreign to you, let me explain. Most development tools are open-source projects, you can’t really do much with the source code of something if it’s an application supposed to run on your computer. In order to run an app, you have to compile the source code into an executable file.

If you have a unix/linux background, that’s something you would be used to do, it would also increase dramatically the chances that you sport a neckbeard. So I’ll assume almost none of you do.

Compiling source code can be tricky, there are dependencies (other executables that this application needs in order to function) and configurations that can turn a simple installation into hours of scouring for contradictory bits of information on obscure forums.

That’s where Homebrew comes it. It’s easy to install and the way it avoids making you configure and check for dependencies is by offering “formulas” – simple little scripts written in Ruby (which comes bundled with Mac OS X) – that will do dependency checking and configuration for you. And while Homebrew is a command line utility, it gives you a lot of intelligible feedback on what it needs from you, and what it’s doing.

Better yet, unlike MacPorts, Homebrew installs itself within your /usr/local/ directory and makes you the owner of all directory it installs applications into. It sounds banal, but it means you’ll never have to “sudo” (perform actions as the administrator account) when you need to install or upgrade executables.

The other advantage of installing things in /usr/local/Cellar is that Homebrew does not override any system installation. All it does is “symlink” (think of it as putting a shortcut) to its own Cellar.

What can I install with Homebrew?

• Ruby
• Python
• NodeJS
• ffMPEG
• MongoDB
• Redis
• Memcached
• MySQL
• PostgreSQL
• MacVim
• YUIcompressor
• ImageMagick
• Git
• Clojure
• Erlang
• CoffeeScript

And the list goes on, just type brew search something to find out if a formula exists. If you want the whole list, simple type brew search.

Great, where do I get it?

Learn more about Homebrew here

Install it quickly with these simple instructions.

There were hints along the way. As soon as I started making websites during my last year of middle school, I became addicted to sharing things with the word, even if that world consisted of 10 random visitors and 20 search bots. When I became billingual after teaching myself English through tv shows (mainly), movies and books, I had this urge to try and help people around me (in France) to learn to stop being afraid of their lousy accents. Shame is one of the worst barriers to knowledge.

Finally more recently, as I was explaining a concept to a fellow student at Full Sail who was much earlier in the cursus than I was at the time, one of my favorite instructors looked at me and asked me if I had ever considered teaching. I was a little surprised by the question, then I realized what he meant. Teaching there, at Full Sail. I had never even considered it before, it flew completely past my radar, and somehow the thought felt right.

Since then I’ve noticed that every time I explain a design concept, an object-oriented principle, or one of the tennet of skepticism I somehow become almost instantly more at ease with the topic I just attempted to convey to another person. This practice of breaking down knowledge to its core essentials and bring it to the level of a specific person with specific biases and preconceptions is addictive.

I think I’m a slow learner, and while it’s disadvantage in many aspects it allows me to somehow remember better than some people the stumbling blocks I struggle with as I was learning a concept. While it doesn’t automatically make me a better teacher since the explanation matters, the ability to empathize with a student facing a seemingly insurmountable obstacle is something invaluable in an educational setting.

I believe many educated people forget how much they struggled to understand difficult concepts as soon as they do understand them. I vaguely remember reading about a psychological study outlining how this functioned. Basically, people have a tendency to forget how long they failed to grasp something and what exactly prevented from doing so. And with this post-success amnesia comes a general attitude of slight disdain toward people who seem to struggle more than you remember struggling yourself. It’s yet another cognitive failibility of the human mind but I think it explains why so many accomplished scholars make poor teachers.

Three years ago, I received a national security letter (NSL) in my capacity as the president of a small Internet access and consulting business. The letter ordered me to provide sensitive information about one of my clients. There was no indication that a judge had reviewed or approved the letter, and it turned out that none had. The letter came with a gag provision that prohibited me from telling anyone, including my client, that the FBI was seeking this information. Based on the context of the demand — a context that the FBI still won’t let me discuss publicly — I suspected that the FBI was abusing its power and that the letter sought information to which the FBI was not entitled.

How somber that America’s worst enemy turned out to be its own government, using the threat of terrorism as a way to destroy the very tenets of what it should have been standing up for: the American Democracy.

If I hadn’t been under a gag order, I would have contacted members of Congress to discuss my experiences and to advocate changes in the law.

If this sentence doesn’t chill you to the bone, realize that this is something to expect from a repressive dictatorship.

I started to properly learn about American history after 2001, and I found it fascinating. Here was a country founded on a near-scientific approach to perfecting government, with the idea (taken from Montesquieu) that there needed to be a separation and balance of powers. Instead of trying to imagine what should be forbidden, this country focused on what should be absolutely safeguarded. It agreed on a concise, beautiful and imperfect definition of what it meant to be part of a free society.

But despite my continued hopes, America has proven to be shaken off balance for the last 10 years. Instead of reacting like a free nation, it was constricted by fear and paranoïa. It turned into an Ouroboros, devouring itself for an untangible threat.

I wouldn’t be here today if I had lost hope, but America needs to wake up.

I think that if you remove the group of people for whom the rules of their religion are so central to their being that that have all sorts of hatreds, and instead look at what is uncomfortable about atheism for the large group of reasonable people who remain, the answer would be that people dislike extremism of all kinds. Atheism is as extreme as fundamentalism. It’s not nearly as harmful, but ideologically, it is as extreme. For atheists and fundamentalists, the question is answered. For everyone else, there is a long way to go.

And here’s mine to hers:

That’s a common misconception.

Atheism is the absence of religious dogma, it couldn’t be more different than fundamentalism which implies the strict orthodox application of religious dogma without concern for modern society. Atheism is absence of a doctrine, without doctrime there is nothing to be “fundamental” about. That’s about it. How one could even begin to describe that as extreme boggles my mind. But if you can make a solid argument as to how exactly, I’ll be sure to listen.

As many atheist choose to describe it, Atheism is about as extreme as refusing to believe that there is Flying Spaghetti Monster out there in the universe because you can’t prove to absolute certainty that there isn’t. It just happens to be extraordinarily unlikely.

Now if it is extreme to find reality sufficiently elegant a companion that one doesn’t wish to agree to the existence of supernatural beings with powers defying just about every law of nature for comfort or sense of meaning, I’ll gladly join the fundamentalists, I’m they will be as open to logic and reason as I am.

That said, I almost wish Atheist were despised for their extremism as you believe it would be easier to dispell. In truth many Americans think them without morals whatsoever because they cannot conceive of morality or ethics without religion.

Bear in mind, this is not to say that there aren’t extremist atheists (quite a difference here) and misguided ones. I’ve met a few of them and most often in and around campuses here. Many of them were recent apostates who are enraged enough to draw generalizations and behave in a way that is not condoned by anyone civilized (religious or otherwise).

But if I could leave you with a lasting thought it would be the revealing discovery recently that self-described Atheists & Agnostics were found to be more knowledgeable about Christianity, the Bible and other world religions than any other group of religious Americans. If this doesn’t make you doubt your assumptions about Atheists, nothing will. Opinion based on knowledge isn’t extreme, it’s reasonable.

PS : I found this thorough takedown of the fallacious argument I tried to quickly tackle above on Atheist Revolution blog after I wrote my response. I think it covers all the bases I didn’t and still addresses the (rare for now) case of atheist extremists.

The thought that they were doing this to help younger fellow human beings going through the same shit didn’t reassure her, it seemed to make her angrier.

I didn’t understand, I think I tried to, but I couldn’t. I thought she may have something on her mind, something affecting her outlook on things, something bothering her and making her pessimistic. She denied it, but I honestly didn’t want to accept that.

It was rude of me I’m sure, but I can’t help it. Optimism isn’t escapism. I don’t ignore all the bad in the world to sleep better at night. But humanity has never done better. We’ve never lived so long, never known so much about ourselves, our planet and the Universe.

We’ve never been so peaceful either. It’s something most people don’t only find hard to believe, they refuse to.

Crime & warfare have decreased so much that most deaths today are due to age-related diseases, it’s unprecedented in the history of man. Cardiovascular diseases — the greatest killer in the world — accounted for 30% of worldwide mortality in 2002. War & violent crimes (bundled together with suicide and other causes) are only responsible for 3%.

Diseases still rule the death toll. Yet if I had lived a mere 200 years ago all I could have hoped for was a mere 10 years to live past my upcoming twenty-sixth birthday. Today I can look forward to a good 50 years, perhaps much more.

That doesn’t mean things are easy for everyone, and too recently racial and sexual discriminations are a harsh reminder of that. Yet once again, things are going better. It’s not a fallacy to say that a black man born of an African father and and American mother at the head of the greatest superpower in the world is an outstanding event in a country that two centuries prior saw blacks as nothing more than inferior beings only fit for slavery.

And while the amoral defenders of morality still deny basic human and civil rights to homosexuals or anyone that challenges their narrow iron-age mentality, there too things are improving, around the world.

How many more moments of joy, pain, pleasure and sadness will we enjoy? How many more things will we have the opportunity to build? How many beautiful sunsets and moon rises will we have the chance to witness? How many people will we discover who will affect the course of our lives those we already met did? How many answers will we find and how many more questions will we think of?

I don’t know.

All I know is that it gets better. But I couldn’t always afford the perspective to see that, and fellow human beings’ kind reminder would have helped.

I know that much.

“You can’t understand Google,” vice president Marissa Mayer says, “unless you know that both Larry and Sergey were Montessori kids.” She’s referring to schools based on the educational philosophy of Maria Montessori, an Italian physician born in 1870 who believed that children should be allowed the freedom to pursue their interests. “In a Montessori school, you go paint because you have something to express or you just want to do it that afternoon, not because the teacher said so,” she says. “This is baked into how Larry and Sergey approach problems. They’re always asking, why should it be like that? It’s the way their brains were programmed early on.” – Steven Levy, http://www.wired.com/magazine/2011/03/mf_larrypage/all/1 Larry Page Wants to Return Google to Its Startup Roots

It’s sad that so many children are berated out of asking crucial questions like “Why?” by parents, teachers and relatives who perpetuate the medieval notion that curiosity killed the cat.

Curiosity is the fuel of inquiry, it’s the essence of Science. It should be safeguarded at all costs.

This is not that say that a mischievous kid who is testing boundaries by uttering an endless stream of “why this? why that?” at every explanation given to him shouldn’t be punished for abusing people’s patience.

But too often true curiosity and wonder at the mysteries of life and the universe is sacrificed because some brats have abused the system, ruining the chance for all the other bubbling little minds to ask questions their elders too often haven’t thought of asking, or worse, have given up on trying to ask.

As a kid I was revolted against this idea that children “shouldn’t talk back” which in France meant that if an adult offered an irrational proposition, children should be punished for even questioning the validity of such a proposition with their natural skepticism. Thankfully, it was something that my parents never enforced on me, they would do their best to answer me honestly and on some rare occasions even admitted ignorance, giving me a clue early on that adults didn’t necessarily know everything. Despite that, the rest of my family and even strangers often did their best to try to plant that awful shame of questioning appeals to authority.

The more I read about the Montessori approach in articles like the recent one from the Wall Street Journal – The Montessori Mafia, the more I come to think it may be one of the solutions to the many woes of modern education, which sadly is nothing short of an oxymoron for now.

What I’ve noticed is that is never too early to talk about it, because most of you, I’ll tell you right, will not talk about it until it’s too late. Your idea sounds exciting, amazing and maybe challenging in your head. But your idea has never been out in the real world, it never had to cross the street and watch out for better ideas zooming by. In your head your amazing idea is never going to get shot down by a one-liner from a friend you expect to be in your target demographic.

Now I’m certain some of you think that if you talk about your idea someone is going to take it. Sure, that can happen, but this is a school, things like that don’t go unnoticed, or unpunished. If you think you’d rather stay mum about your idea because it might have some weight in the real world, after you graduate at Full Sail, then let’s see if it can even stand on its own legs in our little world before you take it out to the big leagues.

A good idea is infectious, people get excited about it, they want to help you with it, will make suggestions to make it better or you will find out who doesn’t like it, and why.

Exposing your idea doesn’t mean you have to shout it out to the entire school, but you can start testing the waters, as early as possible. Go see course director, a lab instructor, a fellow student who’s early in the program or about to start his final project so you get the benefit of the knowledge he gathered.

If you manage to get someone else excited, do you have any idea how motivated it’s going to make you?

And what’s the worst that can happen? You could learn about your idea. Isn’t that why we’re here?

It was the first time in my life I took a plane — a transatlantic flight — alone. It was hard to express why exactly I wanted to go to NYC like that, in a cold season, alone, with no clear purpose. I remember wondering how my girlfriend at the time would take it, but I couldn’t reason myself, I had to go.

The feeling of absolute control of making a decision by myself, and executing it on my own was exhilarating. I didn’t do anything very interesting for those three days. I would wake up, walk around the city, shop around, eat, take pictures of buildings, billboards and people, then go back to my hotel and browse the web.

One slight excuse I had used on myself was that huge rumors were going around that Apple was going to introduce the elusive iPhone to the world at a special event on the second day of my trip. I wasn’t really familiar with Apple’s practices at the time as I had purchased my first Apple device (an iPod Video 5G) the previous summer at the 5th Avenue Apple Store in NYC with my friend Clément Dague. I somehow hoped the device would be released immediately at Apple’s flagship store and that I could snatch one before flying home, and maybe sell it to pay for my journey.

The iPhone was announced, and even though it wasn’t even on display at the 5th Avenue Apple store I felt like I was closer to technological history being made. It might have sounded foolish if I had voiced that feeling at the time, but I don’t think anyone would laugh at that today.

Walking around the streets of New York, not like a tourist, but like a free man (minus a job and responsibilities) gave me a glimpse into what at the time I only felt was a crazy dream.

A few months later, I met two American girls that are now my friends, one stayed at my apartment that summer, the other one jumped from joy when she realized I was the only fluent English speaker at a house party in Paris a few weeks later.

In August I flew to Quebec with my parents to visit friends and I sneaked out on a Greyhound bus from Montréal to go visit a friend from college with dual citizenship who was working in New York City for the summer. I finally got my hands on that damned iPhone on display at the 5th Avenue Apple Store and called my mom in Canada (for free) with it.

When I came back to France, and eventually to college I couldn’t keep the sound of the world buzzing in my head quiet anymore during tedious lectures on British Civilization. So I sent a text to one of the girl I had met that summer, she replied.

When my friend Guillaume told me he was visiting his brother for Halloween, I bought tickets to Orlando, Florida. A friend from class had never travelled outside of France, I took her with me. We landed on November 5th 2007. When I left on November 10th, I cried.

PS : I’m writing this on February 11th, 2011 from Winter Park, Florida.