Whether you graduated college, wrapped up coding bootcamp, or taught yourself to code, soon enough you’ll be in your first position as a professional developer. Congratulations! But what happens now?
A world of different roadblocks will likely hit you on day one of your new gig. Many of these will arise as a result of what I call tutorial dissonance, which is when developers learning new skills seek out the most up-to-date tutorials or curriculum despite most applications being at least a little bit if not several years behind. Why bother learning Ruby 2.x and Rails 4.y when you can learn the latest and greatest, right?!
Therein lies the problem. Almost every Ruby on Rails application you will be hired to work on is going to be at least a few or several versions behind the most recent release. I’ve worked for companies running Rails stacks ranging from 1-3 years old, some even older than that. This is common in the world of software development.
Upgrades take developers away from their day-to-day work, introduce breaking changes, and are generally considered a very big headache, so they tend to be avoided.
In my spare time, I mentor less tenured developers while they work on open source projects for a non-profit.
One of my mentees was recently hired as a part-time developer. His very first professional role, so we were all crazy excited for him! He was understandably thrilled, too — until he went to install the project on his M1 Mac and ran into roadblocks.
In this blog post, I will cover the three common issues my mentee encountered that arise from running on older versions of Ruby, Rails, and Javascript, and what you can do to make onboarding easier.
The three issues I’ll go over are:
- Mismatched system dependencies
- Mismatched Javascript and Asset pipelines
- Outdated documentation
Mismatched System Dependencies
The first bug my mentee ran into was: an error occurred while installing Nokogiri 1.10.10 and bundler cannot continue… . He spent hours googling and googling only to find out that he needed to change the configuration of his dependency manager (in this case Bundler). He ran:
$ bundle config build.nokogiri –use-system-libraries
$ bundle install
And it worked! For a bit, anyway.
During the following bundle, he ran into: an error occurred while installing mysql2 and bundler cannot continue… . Another rabbit hole was in front of him. He learned that for database related gems to bundle, the underlying database must be installed and running on the machine! So brew install mysql2 got him moving forward.
Once that was fixed, he was up and running! Well…almost. His bundler had successfully grabbed all the Ruby gems he needed.
Mismatched JavaScripts And Asset Pipelines
The bundle was complete. Time to start the Rails development server! The server ran. My mentee went to view the page, and BOOM:
Sprockets::FileNotFound…
The assets weren’t loading like they were supposed to. He struggled hard with this for three reasons:
- He had never seen or used Sprockets before.
- He never really understood how Rails loads assets either in development or production because he was never taught during bootcamp.
- The application’s README file never documented the much-needed commands of npm install bower -g and rake bower:install as part of the setup process. My mentee had never heard of Bower before —many tenured developers likely haven’t. It is an asset compiler that was popular several years ago, but was quickly replaced with Webpack.
The long-term solution was to run the Bower commands. Since they were not documented anywhere in the README file, this led to unnecessary challenges for my mentee – which leads me to my next point…
Outdated Documentation
In the case of my mentee, the README file for the application had not been updated in several months. There was no setup script or any other hints left anywhere. He was stuck trying to Google for answers very few had ever run into before.
Needless to say, this caused even more frustration. Had a previous developer taken the time to update the README, the project would have seen a much quicker onboarding and maybe even forward momentum from day one. But sadly, that was not the case.
With the commands running and the application now fully working in his development environment, my mentee updated the README file. It was his very first commit/PR to that project. Hopefully no one else will hit that same roadblock ever again.
Solutions to Avoid a Setup Nightmare
As a newly minted professional developer, what can you do to make your onboarding much easier than that of my mentee? Here are a few ideas:
1. Avoid focusing on the latest and greatest tutorials.
LEARN FROM THE PAST. Usually, new features shipped or “magic added” result from a pain point from the past. Take some time to view those pain points. Understand them. Understand how they were mitigated. Come prepared to run into them yourself. React, Angular, and Vue didn’t always exist —at one point, developers used jQuery. Before that, vanilla JavaScript. There was no need to compile, transpile, or any-other-pile JavaScript, it was simply added to the HTML and it worked. Things have become significantly more complex since then. Dig in on the evolution of Rails more and read the changelogs, there is a wealth of information there.
2. Ask questions when you don’t understand the why or how.
If you see a tutorial that says something like: “Next, run this command: ______________” and you can’t explain the why or how of that command, STOP and ask what it is doing and why it is doing what it does. It’s important to understand the need and learn how Rails works under the hood. Here are some questions to ask yourself:
- How does it load assets?
- How does it parse incoming requests (before it hits the routes.rb file)?
- What files are loaded on server start?
- What files are loaded dynamically/without a server restart?
Dig in on the internals!
3. Leave the README file more updated than you found it.
Every time you add a new dependency, change a configuration, or otherwise make setting up the application more complex, update the instructions! Avoid leaving future developers high and dry and don’t assume that the next developer will be onboarding with years of experience. Once in a while, try removing the project entirely from your machine and start from scratch. Can you get things working with only what’s in the README? If not, it’s time to update!
If you are a relatively new Ruby on Rails developer, welcome to the community! I hope you never have to spend hours trying to get an application running locally. But if you do, fear not! It happens to all developers at some point in their career. Take some of the lessons above to heart, put them into practice, and hopefully you can leave the codebase a little bit better for the next software engineer. Happy hacking!
