Sticky steps? #126
Comments
|
Hey! Thanks for reaching out 👋 So are you creating a bunch of single step tours? Or are you creating tours as a series of comments for a single codebase? Also, how are you storing/persisting the tours if you don't commit them? Do you record the tours, and then move the files someone else? I just ask since you can export tours, and CodeTour allows storing tours in GitHub Gists, and I'd be curious to hear if that's helpful for your workflow 👍 Regarding making the steps sticky, there are a few options currently:
Would either of those work for your workflow? Both of these options rely on "snapping" the tour to a specific version of the codebase, and therefore, might not be great if you want to have your tours be "sticky" to the codebase. But they have the benefit of not requiring the codebase itself to be modified for your personal notes. In order to allow a tour to remain in sync with the latest codebase changes, we're exploring two options:
In both of these cases, we'd need to make the recorder allow authoring tours easily, but I think we could address that challenge. In general, I'd love to hear your thoughts, since this is an area where we need a ton of great feedback on. I'd also like to improve the workflow for creating personal notes, and so learning more about your use case would be very helpful. Thanks! 😁 |
|
Hi Jonathon,
What I do is create a single tour with a bunch of steps. In the future I might group them depending on code base section but right now I use a single tour.
The tours are persisted locally only. I use a global .gitignore rule to ignore .tours Your ideas are also great, I will look into both in a few months when I get a second machine.
Regarding making comments sticky, regex matching would require more work and in my view reduce the ease of use of creating quick, private comments on a line or code block. I value the speed of a simple GUI click, typing of the private comment, and save. Easy to comment, easy to return to later.
So what could improve the current drift issue? Comment markers on code blocks sound ideal. To handle updates to changing code blocks, perhaps the code block/marker is flagged as "altered". It then has a visual change marker at an alert/caution/yellow level to visually indicate medium priority (not all changes outdate a private comment).
CodeTour also references this altered code-blocked tour/comment under a "altered code blocks" section. Ideally this section allows jumping through altered steps just as it would with a normal "tour."
When a change is complete, a "mark updated" button is clicked to move the step out of altered status. The button could also be clicked if updating the block is not needed or desired.
The changed section could continue to nest the tour. Or it could dump the changed sections globally. Nesting is probably more usable for the use cases of others. In my case a global dump would work well.
Hope that helps and great job so far with CodeTour!
…On Sun, 31 Jan 2021 18:01:55 -0800 Jonathan Carter ***@***.***> wrote:
Hey! Thanks for reaching out 👋 So are you creating a bunch of single step tours? Or are you creating tours as a series of comments for a single codebase?
Also, how are you storing/persisting the tours if you don't commit them? Do you record the tours, and then move the files someone else? I just ask since you can [export tours](https://github.com/microsoft/codetour#exporting-tours), and CodeTour allows storing tours in [GitHub Gists](https://github.com/microsoft/codetour#github-gists), and I'd be curious to hear if that's helpful for your workflow 👍
Regarding making the steps sticky, there are a few options currently:
1. You can [export a tour](https://github.com/microsoft/codetour#exporting-tours), which will include the associated code in the tour file itself, and therefore, can always be replayed, even if the annotated code changes.
1. Additionally, when you record a tour, you can choose to associate it with a [specific commit](https://github.com/microsoft/codetour#versioning-tours), and whenever you replay the tour, it will use the version of the files in the original commit.
Would either of those work for your workflow? Both of these options rely on "snapping" the tour to a specific version of the codebase, and therefore, might not be great if you want to have your tours be "sticky" to the codebase. But they have the benefit of not requiring the codebase itself to be modified for your personal notes.
In order to allow a tour to remain in sync with the latest codebase changes, we're exploring two options:
1. Injecting a comment "marker" into the codebase, so that the step can be associated with the code block, not a specific line. This might not work for you, since you don't want to include any changes into the codebase?
1. Associating the step with a line of code via a regular expression. That way, if the line number changes, then the tour would remain "sticky" to it.
In both of these cases, we'd need to make the recorder allow authoring tours easily, but I think we could address that challenge.
In general, I'd love to hear your thoughts, since this is an area where we need a ton of great feedback on. Thanks! 😁
--
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub:
#126 (comment)
|
Hi, first of all I wanted to say I love the plugin! I use CodeTour for private commenting, to help me personally explain bits of code without cluttering the repo with comments.(In my use case I don't commit the
.tourfolder. I also don't "run" tours, I just use them as hidden/popout comments)What would you say is the best way to make a step "sticky" so that file changes won't drift a tour step from its associated code block? I have mostly used line based steps but now see that maybe selecting a code block first will better connect the step to it. Is that true?
If the code block is modified is there potential for the step to still drift? What type or level of modification would cause that?
Thanks!
The text was updated successfully, but these errors were encountered: