search

microsoft / codetour

VS Code extension that allows you to record and play back guided tours of codebases, directly within the editor.
https://aka.ms/codetour
MIT License
4.37k stars 116 forks source link

Annotate pull requests #72

Open lostintangent opened 4 years ago

lostintangent commented 4 years ago

Currently, CodeTour allows you to record tours that are persisted to a repository (as files within a “.tours” directory), and are meant to be long-lived/versioned assets, that help explain the codebase.

However, it would also be valuable to record tours for pull requests (tweet, tweet), so that authors could provide a guided walkthrough of their changes, in order to make it easier for reviewers to understand them, and as a result, potentially provide more meaningful feedback!

Tours can already be associated with a specific Git ref (branch/commit/tag), however, we’ll need to add support for recording/playing back steps on diffs, not just files. Additionally, the following are some open questions we’d need to investigate:

  1. Where would the tour be persisted to? Since the tour would be documenting a PR (which is a short-lived asset), it seems potentially strange to write is as a file in the repo. Maybe it makes sense to write them as a gist on behalf of the PR author? We already have basic support for that that we could potentially re-use. However, maybe it makes more sense persisting the tour as comments on the PR itself. That way, they’re viewable from both GitHub.com, as well as in VS Code.

  2. How could the tour actually be associated with the PR? I’m not sure if GitHub PRs support arbitrary metadata, but their might be “hacks” for enabling this relationship. That said, if we wrote the tour as a gist file, maybe we could simply add the gist ID to the PR’s description somehow? (possible solution?)

  3. How could CodeTour hook into the GitHub Pull Request extension, so that tours can be easily recorded/played back, as part of the existing flow for creating/reviewing PRs? Depending on the answer to the above, CodeTour would potentially need to detect that the user is creating/reviewing a PR, and then read/write to the PR’s description (CC @rebornix)

MSAdministrator commented 4 years ago

My first thought is what level of coded tour is needed? I’m not sure an entire video is needed but I’d through out other ideas:

  1. Ordering commits may be an option
  2. Possible to have a config / settings file which plots the code flow and in turn the VS Code extension would use this file to replay.
  3. A gist is another option
  4. You could add git notes with the config/details but not sure how this may impact the repo.

Just a few ideas.

lostintangent commented 4 years ago

@MSAdministrator CodeTour is already based on a config file that is used to record/play back tours. But for the purposes of enabling PRs, it feels a little heavyweight to have to write that file to the repo. Additionally, I don’t believe GitHub supports git notes. So the more I think about this, the more it seems like a decent idea to use gists for this.

The main downsides to that solution are: gists aren’t private, and therefore, this solution wouldn’t accommodate private repos on public GitHub (GitHub Enterprise includes support for “tenant-private” gists). We could use secret gists, that wouldn’t be easily discoverable, but for some companies, this probably wouldn’t be acceptable.

phrohdoh commented 4 years ago

This is a great idea, but I just want to note: please don't engineer this in such a way that github is placed above other git hosts (even with MS having an obvious interest in that).