Comment UI and experience

[bamurtaugh]

As discussed today, it'd be worthwhile to revisit Live Share comments.

• Is there user feedback (or telemetry, although we'd want to avoid posting that here publicly) demonstrating a need (or no longer need) for comments?
• There are some experience issues:
  • Turning off comments doesn't always turn them off
  • They can feel in the way and separate from the actual code

cc @derekbekoe @fubaduba @isidorn

[danielbee]

I've just started using Live Share and the comments feature got me really excited. I'd like to use live share to run through code and do a design review with a few collaborators. I was really disappointed to learn that this feature might get sunsetted.

Current Experience

The current experience is fantastic in that I can very quickly add a comment that maybe explains the design intent or explains why we wouldn't do something in a certain way or maybe captures a future todo related to that line of code. Then someone else on the collab session can add additional flavour or engage in a text-discussion around that code-block.

Eventually, someone will take an action to translate these in-the-moment comments into github issues (bugs, enhancements, doc changes, feature-requests, discussions, etc), but it's a little bit too much hassle to do that during a fast-paced review meeting.

We also don't want to add literal code comments, because then we'd need to commit changes and trigger a whole set of CI/CD workflows.

The Problem(s)

The most severe problem I have with the current implementation of comments is that they are completely lost when the live share session ends, which renders them almost useless. This is especially worrying, because if I suddenly lose internet connection and the Live Share session ends, I've unintentionally lost those comments and have no way or time to back them up!

• This has been raised before : https://github.com/MicrosoftDocs/live-share/issues/4552

An additional problem is that the comments don't support tagging, so it makes it harder to then do this post-discussion triage into github issues.

An additional problem is that the comments don't support markdown, so links are often very messy.

Suggestions

• At the very least automatically save the comments in some format (easiest may be json, but the comments themselves should be markdown).
  • Setting required for default save path (it probably shouldn't be your workspace)
    • Sensible default location would be a new .live-share folder with a filename of <time_stamp>-comments.json
    • You could have a setting where you could choose if this file gets created in your workspace settings folder, user settings folder or a custom path.
      • If file gets checked-in or is in a shared workspace, then upon opening the workspace all the comments can be seen in the comments panel, with a timestamp and some metadata regarding the liveshare session.
    • trivial to add a .gitignore for .live-share if desired.
  • Then I can at least choose to upload this file or json -> markdown -> pdf and attach it to a design review / release review, where we can later triage to create issues.
  • Everyone who enters and then leaves a Live Share, should get their own local copy of the comments.
    • If I've been brought on to do a design review for a junior engineer, and they've triggered the Live Share. I don't necessarily want/need to force them to upload and triage the comments file. I want to be able to upload it and triage it myself.
    • json file should have some metadata at the top indicating who initiated the Live Share session, who were the participants and what the timestamp was when you joined and left.
      • json file is then basically just a list of comments, with objects for filename, code-line, author, description and replies (which are then another list of comment objects).
• Ideally, if the code is a repo on github that I have access to, then all the comments get chucked into a single discussion on that github repo (ideally) in real-time. Or, you add a button to the context menu to "Upload to GitHub Discussion" or something.
  • Auto-name the discussion (add a setting for default naming) something like "Live Share Code Comments "
  • In the discussion description, give all the metadata regarding the Live Share session
    • The participants, what timestamps they joined & left
    • A link to the Live Share collab session (with a privacy setting enable/disable this default behaviour)
    • etc
  • Code comments are individual comments on the discussion, formatted like:
    • start with a hyperlink to the code line in the repo
    • have an "author", which might be plain text for anonymous users, or might be a hyperlink to github profile if they've authed in that way, or might be a microsoft account email address hyperlink if they auth'ed in that way.
    • then the rest of the text comment.
  • Then, after the Live Share session, you could continue the discussion on your github discussion, quoting specific comments, creating new issues that reference the comments, which in turn create pull requests etc.
    • This further promote the microsoft / github code collaboration ecosystem, and promotes a great feature that exists on github already.
  • Maybe you're not involved in the Live Share session, but you happen to see a new discussion is created on the github repo that you also collaborate on. You could see the comments come in, in real time and add your own thoughts, which then is propagated back to the Live Share collaboration session. Maybe after some back and forth, you decide to jump into the collab session as it happens.
• Perhaps there's integration with microsoft teams. Since the Live Share Audio feature is removed, I need to have a voice call over Teams / Slack / Discord whilst I'm doing a Live Share. All of these apps support discussions during calls, maybe there's an opportunity to integrate nicely with these apps. (I'm assuming Teams prioritised first because Microsoft ecosystem)

Concluding Thoughts

Whilst the exact details need ironing out and sense-checking, I think the broad strokes of the suggestion would be a better implementation of this feature. The comments have value, because they can be saved, tracked and mentioned in future issues. The github ecosystem is heavily integrated. And options exist to integrate further with third party communication apps.

Basically, code comments could be an invaluable tool during Live Share Collaboration sessions, all it needs is a bit of integration or export capabilities. Please don't sunset them!

At the very least, spin it out into it's own separate extension, "Live Share Comments" and make that part open source rather than removing and deprecating it entirely.

I appreciate that your telemetry may indicate that no-one uses the feature yet, but I hope you can see that this might be due to the current implementation's problems and could be resolved with a nice integration or export ability.

I'd love to get your thoughts on this @derekbekoe / @bamurtaugh !

Maybe there's a better & separate tool/extension that addresses this use-case? If so, please let me know!

[derekbekoe]

@danielbee Thanks for the detailed comment. Unfortunately we’re not able to prioritize this right now. However, rest assured that we value your input. We will keep this issue open just to ensure we can continue to gather feedback. Thanks.