Introducing: Tutorial Pull Requests

An effective way to ease people into your breaking changes

It’s been a year since I joined Skillshare, and one thing remains true: every day brings a new challenge. A while ago, my team and I were migrating the platform from Backbone to React. Today, we have a whole library of UI components which brings not only React to the table, but also React Apollo, Styled Components, Recompose (don’t worry; Hooks are coming), Jest, React Testing Library, and a whole lot more.

As the library evolves, other teams are eager to use it for their own work—after all, React is lovely.️ However, introducing new things always carries a great responsibility: you need to onboard developers effectively.

The easier something is to learn, the higher the adoption rate.

When it comes to easing information into peoples’ heads, we have some options: lunch n’ learns, live programming sessions, a handy Markdown-flavored wiki, or links to the dozens of articles that got us where we are. All of these are fine, but there’s one more we could use.

Pull Requests as a Learning Resource

We already had to dance that dance…

When adopting new frameworks or concepts, we already had to spend a lot of time figuring out how it works. We had to decide whether it was the right choice, what risks it brings, and ultimately how to implement it.

We wrote code for that.

Luckily, there also might be a pull request somewhere with our commit history, review comments, and every drop of sweat expended in bringing our idea to life.

A pull request is a journal of our pains and joys materialized.

The best part? It serves as a window into our reasoning.

The Tutorial PR Format

AR for your pull requests!

Linking fellow devs to our pull request on GitHub and telling them, “Here! Just read the code—you’ll get it,” is not enough. They have code to write and deadlines to meet. We don’t drop them into our code empty handed and expect them to come out unharmed. No. We need to provide the right tools for the job.

So, how do we do that?

Enter Tutorial PRs — good old pull requests but super-charged with walkthrough comments!

No magic here; it’s only adding an index and explanatory comments interconnected through navigational links.

Here’s how it works:

Disclaimer: we use GitHub at Skillshare, so I’ll base my examples on that. I’m guessing this format can be easily ported to any other Git provider.

1. The Description