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
We need to make it clear that our pull request is a Tutorial PR. When people open it, their eyes will land on the title first, then the description. Prefixing the title with [Tutorial PR] is one option, but I found it too intrusive when looking at the pull request list. Instead, adding an eye-catching notice at the very beginning of the pull request description makes a more elegant alternative.
We start the description with a HUGE notice to make people stop. Then comes a statement of the topics covered, and a link to the index (which we’ll be adding on the first file of the change set). At the bottom, we have the standard pull request summary (overview of changes, requirements, how to test, etc.).
Markdown code available here.
We can also add a colorful tutorial label to our PRs so they stand out among others in the list. If we want to see all of the Tutorial PRs, all we have to do is filter by label.
Convenience is key here.
2. The Index
The rest of the content goes on the actual change set (the Changes tab.) We’ll be making a self code review with explanatory comments on our own files.
A self code review or individual comments—that’s your choice! However, the former allows testing navigation and revise before adding everything.
The very first comment we’ll be adding is the index, which makes sense to put at the very beginning, on line 1 of the first file.
The index contains the title of the covered topic, a short description, a link to the first explanatory comment, and links to the rest of the topics.
Markdown code available here.
3. The Code Range
An explanation without any context fades away from a reader’s brain rather quickly. If we show code first, they’ll connect the dots while reading the explanation. So, instead of linking directly to the walkthrough comments in the index, we’d rather link to the line of code where the code covered by the topic starts.
We’ll call this “The Code Range.”
As you might have guessed, depending on the size of the screen, the walkthrough comment might be out of sight at first, but don’t worry! Most readers scroll down when lost; they’ll find it sooner or later.
Only put the necessary amount of code in the range to cover the topic effectively.
4. The Walkthrough Comments
Once our readers have looked at some code, it’s time to do some explaining. For this, we’ll add a comment at the end of the code range. It’s helpful to add the lines we are covering on the main topic and subtopics. Add just enough information so the reader understands what the code does without getting bloated.
Use code snippets, diagrams, memes, etc.—make your comment pretty! Here’s everything you can put on a GitHub comment!
Markdown code available here.
Once we’re done explaining, we’ll add links to the next topic’s code range.
5. The Conclusion Comment
The last walkthrough comment differs from the others in that it includes further reading materials (I usually add videos too), an optional last note, and links back to the index and the pull request itself.
Nothing special going on here—just making navigation easy!
Markdown code available here.
Get the Source Code
The full Markdown source is available on GitHub! Also, you can check out a sample Tutorial PR here.
Conclusion
That’s it! There’s no magic to Tutorial PRs, and I guess that’s the actual charm of the thing. We’ve been doing this at Skillshare for a while now and it has proven to be quite effective in making pull requests with foundational changes or even revisiting of existing features far more digestible. Don’t know—if you like it, maybe give it a go and see how it plays out!
As a closing note, I’d like to say I wish this was an official feature on GitHub—like a separate overlay or something. It would be a lot more convenient. Comments will get outdated and go away if I push changes—requiring some re-adding—and it’s not too nice to have walkthrough comments polluting the Conversation tab.
Why is this not a feature, GitHub!?
Pretty, pretty please?
Got questions, comments, or anything you’d like to share? Find me on Twitter as @ldiego08. Don’t forget to 👏 and share if this post was helpful!
Enjoy Doing Stuff Like This?
Here at Skillshare we tackle huge challenges using the latest and greatest technologies — and we love it! ❤️ Are you one of us?
What are you doing away from home then?
