Allow replaying code tours on GitHub

[mathieudutour]

A lot of devs don’t use vs code, it would be amazing for them to be able to play the tours on the web, without needing to download vs code for that (I think it’s fair to require vs code to record a tour)

[lostintangent]

With some help from @nat and team, I'd love to explore if we could build something like this directly into GitHub itself, without relying on a browser extension. I built this initial experience into VS Code, so that I could explore the idea/UX. However, I completely agree that it's value extends far beyond the editor, and GitHub is the perfect home 👍

[mathieudutour]

That'd be amazing, I'd love to help explore that idea

[nat]

If you have a mockup of how it could work in GitHub, that might help kick off the conversation. Thinking about how to avoid metadata bit rot would also be good.

[lostintangent]

@nat I'll be thinking through the decay problem this week, and I'll throw together some initial mockups as well!

[rand]

@lostintangent would associating the code tour with a concrete tagged release help with the decay problem (and add a more static link to the resource)?

[lostintangent]

@rand I think so! I just made an update to the recorder, which asks you which git ref you'd like to associate the tour with. It displays all available tags, and lets you select either a one of those tags, the current branch, the current commit, or "none" (which lets the tour apply to all versions).

When you replay a tour that's for an older ref than HEAD, then it will navigate you through a read-only version of the tour, using the version of the associated files from the recorded ref. That way, the tour is always accurate.

You can also update the Git ref association at any time by right-clicking a tour in the CodeTour tree and selecting Change Git Ref. That will display the same pick-list as above, but will let you "fast-forward" the tour to future commits/tags/branches if it applies. I feel like there's more work that I can do here to make this experience smoother, but this seemed like a decent starting point to prevent "decay" of the tour.

[rand]

@lostintangent that is awesome! i can't wait to get this integrated on the web client side, too.

[themmes]

Spotted your project on HN this morning, cool stuff!

I was thinking to counter bitrot wouldnt it be convenient to actually store the steps in the code commenting. Much like TODO?

// CODETOUR: <#> "<Some title>" #L0-99 ...

Where you..

1. assign the stepnumber<#> manually or leave it out and assign interactively using some CLI later
2. add a title
3. can add a (or multiple) subset(s) of lines (code comments and actual code) to click/spacebar through as a CODETOUR

[lostintangent]

@themmes Thanks for the suggestion! I’ve been considering adding support for this, as an alternate “tour definition provider”. That said, there are a few elements about this approach that have given me a little pause:

1. The comments would clutter the code for everyone that’s reading it, as opposed to enriching the code for only those that are actively taking the associated tour. This might not be a big deal, but in order to achieve long-term traction, I can’t help but feel like being unobtrusive has value. The “side car annotations” approach helps with this, and so it just comes down to the trade offs that teams are willing to make, and how well I can address bit rot by associating the tour with a specific commit/tag. I’m also exploring ways to notify you when a tour should be updated, but that’s a little experimental right now 😁

2. I want the tour to be able to span all file types, and I’m not sure if the comment-driven approach would naturally work in 100% of meaningful scenarios. For example, how would you define a step in a JSON file (since it doesn’t support comments)? Since the role that declarative code/metadata plays in codebases can be a huge source of confusion, I felt like we needed a solution that was fully agnostic to the grammar of any specific file type.

3. A codebase can define n-number of tours, and therefore, a single line of code could actually participate in multiple different tours. Having a single line annotated with two (or more) different tour descriptions could amplify amplify the potential for clutter.

4. The tour would no longer be defined in a single place, and therefore, the benefits of having a human-readable file for quick/easy editing would decrease a little bit. In general, I want the visual editor/recorder to enable easy tour authoring for most scenarios. However, as with any abstraction, there’s commonly value in being able to pierce it for advanced tasks.

I definitely think the comment-driven approach has a lot of value, particularly for reducing bit rot. That said, I just wanted to share some thoughts I had about it, and give some context about why I’ve initially chosen to go with the “side car file” + associating a tour with a commit/tag. These reasons might not matter much in practice, so I’m mostly just thinking out loud 👍

I just filed a separate issue to discuss this suggestion (#38), so we can track it separately from the GitHub integration. Thanks again, and I’d love to hear your further thoughts!

[linonetwo]

There used to be an online version that I really like: partyparrot/codetours

It is dead, but maybe it can be taken as a reference.

[lostintangent]

@linonetwo Thanks! I had no idea there was a previous project called code tour as well 😁

Out of curiosity: what would you think about having a browser-hosted version of VS Code, that allowed taking a tour of any GitHub repo? That way there would be complete symmetry between the web and desktop experiences, but you had the ability to richly browse codebases in your browser too?

[linonetwo]

Yes, back to the time I search for a solution like partyparrot/codetours, I was just looking for a way to share code via a link, it is like carbon.now.sh/ or GitHub gist, but can deliver more context and feels like a tutor.

As for a browser-hosted version of VSCode, I frequently use stackblitz to reproduce bugs when I raise an issue (for example, https://stackblitz.com/edit/react-three-fiberissues120 ). It can load any GitHub repo into a monaco editor and bundle dependencies in the service worker. Its drawback is that it can't install extensions like this codetour extension (for now, but it seems to have some other extensions). And it is only meant for web frontend project.

If in the near future, there won't be an official browser-hosted version of VSCode that ships with full extension API. Maybe you can contact stackblitz team, try to make an extension on stackblitz editor?

---

P.S.

When I want to contribute to a repo, I will go through docs, switching between code and doc to understand the concepts.
But maybe in the future, I can directly read the code and comments via a codetour integrated into Github, it will dramatically accelerate the process I dive into a repo. And clicking a link to view codetour is much easier than clone repo + open it with vscode-codetour.

I guess the more it is integrated into Github, the wider it will be adapted, and the bigger the influence it can make to the open-source community.

[lostintangent]

Now that it's officially announced, I can finally point at this as being the likely solution here 😄 Since the editor-based experience is so immersive, it feels like being able to provide that in a GitHub-native, hyper-linkable, browser-based solution would be a huge step forward. Since Codespaces itself is already fundamentally trying to provide a one-click onboarding experience, CodeTour compliments that goal, by helping onboard to the codebase once you have everything setup and ready to go 👍

In fact, here's a screenshot of me taking a tour of the CodeTour codebase, after simply opening up the repo in a Codespace, in my browser, from github.com/vsls-contrib/codetour. It's so beautiful 🥰

// CC @nat

[lostintangent]

I'm going to close this issue for now, since per my previous comment, I think Codespaces is the natural mechanism for enabling developers to replay a tour from GitHub. If we end up finding that there's strong value/demand in showing tours directly on github.com (as opposed to as part of the editor), we can track that discussion closer to the product team that would implement it 👍

[qmenoret]

Hello, just so you know we started implementing a Browser extension for Code Tours: https://github.com/doctolib/code-tours-github
Doesn't have all features yet, but we use it internally for people that don't use vscode :)