microsoft / codetour Goto Github PK

Just installed the extension and testing it out in MacOS Catalina.

A given comment in the tour has a textarea that one can type into, and it's placeholder text is Reply... but after you've finished entering your reply there's no way to submit the form data and save the reply into the tour

Today, once you start a tour, there is no way to “stop”.

I know you can “pause” clicking the ^ icon in the comment/step panel, but it only hides the tour, but keeps the “comment indicator” in the gutter.

The “Stop Tour” command should end the tour entirely, removing the indicator from the gutter and resetting the Status Bar.

The Stop Tour icon which appears in the Side Bar gave me the wrong idea of Delete Tour. This happened because the X icon is used on other places in VS Code as a delete node element.

I think that because the Start Tour icon uses the play icon, like the Start Debugging, the Stop Tour icon could use the square icon, just like the Stop debugging.

Thank you

I forgot a step and wanted to drag it up in the code tour treeview.

Also, would be nice to have up and down arrows, as a bonus

related to but no the same as #11

If you add a reference to a file in a parent directory, it will resolve as the full path to the file (ex If I have a tour in C:\brianrosamilia\parent\NewThing\, then adding C:\brianrosamilia\parent\my.Config should resolve as ..\my.Config and not the full path).

What happens when I add a tour step like that: it resolves as C:\brianrosamilia\parent\my.Config and clicking on the tour step will not work

What I'm expecting: it resolves as ..\my.Config and clicking on the tour step will work

The nice thing is you can actually just convert the path to relative yourself in the tour JSON as a workaround and everything will work. It even works if you subsequently add steps to that tour in the same file.

I'm assuming you agree with this on a technical level but, in my opinion, relative paths are great for things checked into source control so I feel this is the preferred behavior.

Btw I really appreciate this project. I am using it in a presentation tomorrow (wish me luck :) )

More context here

Original feature request here

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)

Currently, you can author your step descriptions using markdown, which includes support for referencing HTTP-based images. However, you can't currently reference images that are local to the codebase, which is a little limiting. It would be awesome if you could add something like the following to a step comment and it would work (assuming that the path was valid in the current workspace): ![image](./images/foo.png). That way the repo could include the codebase, the tours and any associated images.

Using the tour recorder, you can edit the description and selection that’s associated with a step. However, in order to edit the line number that the step comment is displayed on, you need to manually edit the tour’s JSON file. We should explore how to enable easily editing a step’s line number via the recorder, so that core authoring operations don’t require editing JSON files directly .

When playing back a tour, hitting Ctrl Rightarrow is supposed to step you through the steps. It does for the first step then it stops working, and Ctrl Rightarrow starts moving the cursor through the code instead? I think its a focus issue - if you click to focus on the step window then Ctrl Rightarrow works again for the next step.

The highlight in the tree does not match what is being displayed in the code window, when navigation has been done using arrow buttons. This would be most helpful to know where you are.

Clicking on the arrow buttons in the tree seem to do illogical things. Sometimes they just highlight the step represented by the explorer window, sometimes they cause the next or previous step to appear. Can't figure out their logic.

Clicking on the arrows in the current step window work OK, but it would be nice if the corresponding tree explorer step would highlight, as mentioned before.

Currently, we only discover code tours for the first root in the currently opened workspace. This probably accommodates most scenarios, but we should ensure that devs can open multiple workspaces, and see the tours available across them all.

When adding a step, set the focus to the text area inside of the step so I can start typing

Right click the tour in the tree should allow:

• edit the tour (add, remove steps)
• edit the title and description

Hello!

The explorer view tends to get somewhat cluttered with showing file explorer and open editors etc. How would you feel about having the code tour in it's own view (similar to the docker extension below)?

I think it might be helpful to be able to see that a file you're currently viewing has a code tour step associated with it even though you're not currently viewing a tour.

So in tour mode:

Not in tour mode

It can serve as a hint that this thing might be important and by clicking it you can start the tour at that step and learn why. Might also be helpful as a reminder that if you edit this file you might need to update some line number for the hint itself 😅

First of all - thanks for great extension!

I was thinking that sometimes it's useful to comment on a folder level, rather than the file level.
Imagine I want to create a codetour step that points out that there some special folder that does some magic or stg.
Is it somehow doable?

/cheers

It would be amazing if a developer could start a Live Share session, and then collaboratively walk through a tour with all of their guests. That way, the tour can be taken either offline/independently, or as a group.

Today, all participants in the Live Share session could take the tour “locally” on their own, but it would be much more valuable if everyone could take the same tour, and have their navigations/comments experience fully synchronized.

Currently, tours are persisted as JSON files and written to the “.tours” directory of your repo. However, we could also explore allowing tours to be defined via actual code comments. For example, the following could represent a step definition above a line of code:

// CodeTour: <tourTitle> <stepNumber> <stepDescription>

While this approach could help mitigate tour decay, it also has some potential downsides:

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.

5. You wouldn’t have a natural way to annotate folders or create “content-only” steps (e.g. intro instructions), both of which have come up as being valuable for folks using CodeTour.

Currently, you can authors code tours "manually" by creating the JSON file. However, I plan to allow the user to "start recording", and then navigate across files, clicking on relevant lines, and adding comments visually. That way it's very quick to create new tours for a codebase.

I think to navigate I am supposed to either use the ouse/trackpad and click on steps in the tree OR focus on a step, click CMD ->.

But the latter doesnt work without having to re-focus on the next step. For example:

• open step 1 with the mouse
• click on step 1's visual interface
• click CMD ->
• now click on step 2's visual interface
• click CMD ->

Notice that we have to keep putting focus back on the step. It would be nice to allow full keyboard control to use CMD -> and CMD -< to go forward and backward without having to reset focus.

The Code Tour allows recording comments in a sequence on a particular line.

Feature request: add another type of the tour step - "code input" where the author can record their code input as they code. The extension will then replay their input back to the users on those steps, creating richer interactive tutorials and hands-on user guides.

When you start a tour, the cursor should follow/focus the step position (line).

This would be really helpful if you use a Code Tour not only for navigation purposes, but also when you create a Code Tour which guides the user for “required changes” on files.

Currently, the tour is entirely text-driven. However, it could be really interesting to explore how to allow recording audio as well, and associating that with specific steps in the tour.

I think I found a bug. When hovering a line that has a tour marker, the tooltip displays the same item several times.

The number is not constant, but I haven't found a correlation with the number of steps or step comments.

Edit: the number of tooltip items does indeed go up with the number of steps. My guess is that "repeated" steps retrieved by the following function are not correctly filtered here:
https://github.com/vsls-contrib/codetour/blob/1808b3e06c550635a86b733dda42d265832afdb5/src/decorator.ts#L16

Edit 2: actually, it seems like the whole hover provider is being registered again every time I edit the tour.

Today there is no command to do this. But we can remove the json files to achieve it.

Wicked cool feature ideas ... imagine being able to ask the user where they want to go next?

We could provide paths on the tour to do this. Tour contains paths, paths contain steps

So there would be a hierarchy of these. For example ...

I wan to start by showing the index.html, then steps in the main.js, then the App.svelte component (in a svelte app). At this point I can ask the user if they want to go to the path for building and running the app in the package.json or the path to see the code in the main components.

Paths:

• paths could be rearranged
• could be in a given sequence or out of sequence (dont show build path unless the user asks for that)
• steps can be text OR they are a prompt asking which of a set of paths the user wants to go to next

A simpler version of this would be to simply allow grouping of steps into a path, so a set of steps can be visually broken out and rearranged.

First of all, congrats for the extension! Great idea 👏 .

I tried to use it on remotes (docker), but just noted the extension still doesn’t support it. I could Install in Container but I guess it wouldn’t be necessary.

I’m preparing a PR to help you with that 😁

Thank you for your great extension.
Sometimes we could have multiple tours, which would be good to organize with folders (physical or virtual) or tags with search capabilities

Install extension
Open Command Palette
Choose Record Tour
Get error toast saying: "Cannot read property 'getRepository' of undefined"
Nothing else happens

Currently, the tour recorder allows you to capture a text selection along with a step. However, VS Code allows you to make multiple text selections, and therefore, the tour should respect that, which could enable highlighting a few disparate code spans within a single step.

Thinking out loud ...

The tour begins and the first thing the audience sees is a welcome message. Something to give them context for the tour and tell them what they are about to see.

Title: Welcome to the Tour of Heroes!
Body (multi-line): Here we can put paragraphs using markdown to explain the tour. Good tips might be to explain the path we are taking through the tour. What we're trying to get across. What they will be oriented with.
Author: Name
Tour Lat Revision Date:

Currently, you can select a line of code and attach a comment to it. However, you may want to highlight a multi-line span of code and annotate that. We should explore how to introduce support for doing that.

When I click a line to add a new step to the tour, the cursor should focus in the text input for the new step.

Right now, I only see a button to end the tour. But what happens if I accidentally add a step in the wrong place or the wrong order? Currently, I have to end the tour and start over.

If would be nice to have a button to remove the step.

Currently, you can insert new steps at the end of the currently recorded tour. However, it would be valuable to navigate backwards in the recorded tour, and choose to insert a new step before/after it. Much like you can do with a PowerPoint presentation.

During user testing and getting community feedback, users consistently try to drag files into the CodeTour area to start recording a step of the tour. Perhaps we can enable this functionality, if we can think through the UX of this.

Thank you so much for this plugin! Awesome idea.

Issue:
When using VSCode workspaces, the path to the recorded file is incorrect.
When starting a recorded tour, I get the error:

unable to resolve non-existing file

Love the idea, and whilst we use visual studio code for smaller pieces of work, our many large code base is worked on in Visual Studio 2019. This feature would be great for documenting the various subsystems and cross cutting concerns, just wondered if you have any thoughts on how easy this would be to make into a VS extension ?

The tour step has this data to identify file + line number:
"file": "webfolder/mem6/index.html", "line": 82,
Line numbers can change a lot adding and changing code.
You call this "tour decay", or "line number out of sync".
If you add to the step the text of the line in the code like this:
"line_text":"<script type='module'>"
Then you can :

1. check if all the steps line numbers are still in sync with the code file line numbers
2. If the changes are small, you can automatically find the nearest line with the text and update the line number.
3. If you can not find the text, then it is an orphan and the line number needs manual fixing

Thank you for this great extension. This is the most natural way to introduce complex code to a programmer. And your extension and its user interface is great. Good job !

To allow editing a tour by adding or removing steps.

When editing a step, you can edit the text OK but changing the selection does not get saved. It would be nice if you can adjust the selection - otherwise you are stuck forever with a erroneous selection.

I created a code tour with about three steps. Then I stopped recording. And I wanted to add a new step to the tour and I couldn't find a option to it. So I assumed if I type the same name for the new tour it would ask me to edit it. But instead the existing one got deleted and I lost all the recordings.

Later in the docs I found how to edit the tour. But overwriting existing one without a warning message is not intuitive IMHO. :-)

BTW: I love this extension. I really hope this gets into other editors as well. Thanks.. 👍 💯

Codetour does not work on my workspace. I can record a tour, but when I try to run it, clicking on the steps does nothing, it doesn't seem to "find" the files.

Then I tried to export the tour and I got this error, which suggests that the extension is not creating the right paths to the files referred to by the steps, am I right?

This is the error (just to be clear, the correct path is /home/user/repos/my-repo/index.ts)

Error running command codetour.exportTour: Unable to read file '/home/user/repos/my-repo/my-repo/index.ts' (EntryNotFound (FileSystemError): 
Error: ENOENT: no such file or directory, open '/home/user/repos/my-repo/my-repo/index.ts'). This is likely caused by the extension that contributes codetour.exportTour.

Edit: this occurs only while using a vscode workspace

Currently, the list of tours is blank when a dev installs the extension. During testing, when we showed the extension with a sample tour to a dev, it helped them orient to the extension functionality and UI.

(Partially from #39 )

A suggestion that would have really helped me and I think would be amazing and really set this project ahead of traditional presentation tools :

I was glad to see the tour steps support markdown.

So when I type npm run storybook it shows how I expect it and how another developer would like to read it.

But it would be great if typing that was translated to

▶️ npm run storybook

And clicking the play button would actually run the task.

I was using Codetour to do a live presentation to a group of developers and it was slightly cumbersome to use my (extremely loud) mechanical keyboard to show a few new npm tasks. It would've been great to just click a button and show a task running.

We recently added the ability to export and open tours, which allows you to create one-off/personal tours that don't need to live in the main codebase' repo. However, the currently export/open functionality is limited to saving/opening from the local filesystem, and we should add support for using GitHub gists as well.