(I sent this post to my list a while back. If you enjoy it, and want to read more like it, you should sign up!)
The Rails ecosystem moves fast, way too fast for print. If you’re like me, you want to learn the most recent version of your frameworks and gems. But the best resources are often a few versions behind.
These resources are still useful, though. There’s nothing like a well-edited book, screencast, or tutorial to learn a library’s API, philosophy, and structure.
For example, if the best Rails books only describe Rails 4.0, you should still start from there. When you’re learning a new gem or framework, it’s important to learn why it’s designed a certain way and how all the pieces fit together. That’s hard to get from reference documentation and blog posts, but easy to get from books.
But once you build experience with an older version of a gem, how do you get caught up?
Catching up with changes
Most popular gems have CHANGELOG files in their git repository, like bundler: https://github.com/bundler/bundler/blob/master/CHANGELOG.md. These are a great way to catch up on the big changes from version-to-version. Usually, they’re just a short summary of each major change. But they give you a starting point, so you can do more research on interesting changes.
Many changelogs reference bug numbers on GitHub. If you see an entry in a changelog that has a bug number attached, you can find the bug in the project’s Issues to understand what changed, how it changed, and why it changed.
So, how do you find changelogs? Usually, I just search google for bundler github (if I’m looking for the bundler changelog), and they’re usually on the first GitHub page you see.
If there isn’t a changelog, you can also look at the project’s README or the project’s wiki on GitHub. But since those aren’t designed to help you catch up from version-to-version, they usually take longer to go through.
Using up-to-date reference documentation
When you’re working with gems, you’ll also need to keep up-to-date reference documentation around. That way, you can look up API usage and see examples while you’re writing your own apps.
You can find API documentation for any version of any gem at rdoc.info. But for even faster doc lookup, you should check out Dash or Zeal.
I use Dash, so when I need to look up API docs, I hit option-Space, start typing, and all my gem documentation shows up instantly. It’s a change in my workflow that’s paid for itself many times over.
A few tips on Rails, specifically
Rails is a large project, and the Rails contributors do a great job of maintaining changelogs and documentation.
The Rails guides are good, and they’re also built from the same git repository as Rails, so they’re always up to date.
If you’re trying to catch up to the newest version of Rails, the release notes are the best place to start. For example, here are the release notes for Rails 4.1: http://guides.rubyonrails.org/4_1_release_notes.html
The process I usually take
Putting it all together, this is what I do when I want to get completely up to date on a new library:
- Read a book, tutorial, or documentation about the gem. I usually try to find the newest resource I can. While I’m reading, I build an app, practice, etc. on whichever version I’m learning.
- Find the project on GitHub.
- Read the project’s changelog, readme, or wiki to take me from the version I know to the most recent version.
- If I’m interested in a specific change, google around for it or go through the project’s issues to learn more.
- Upgrade to the newest version of the gem.
- Install the new gem’s documentation in Dash.
- Write code with it!
I don’t do all those steps all the time. But that’s generally the order I go in, and this kind of process is helpful to keep around in case I get stuck on a step or don’t know where to go next.
What if you can’t find a changelog or can’t make sense of the docs?
Sometimes you just won’t be able to get the information you need out of the gem’s GitHub repo or API documentation. When that happens, you’ll have to dive into the code and start reading it.
Surprisingly, reading code is not like reading a book. Instead of reading files from beginning to end, you have to explore the code. This is more of an art than a science, but it’s an important skill to learn. So, I’ll probably have more to say about it later!
What tricks have you learned for getting caught up on gem changes? How do you stay up to date?