Onboarding: Add a quick-start guide or equivalent to README

[ian-h-chamberlain]

Description

Provide a better onboarding experience by leveraging a getting started section in the readme along with an information popup.

Work

• add informational popup on first install of the extension / (on update as well?)
• add new section to the readme for quick-start with gifs around how to use the extension
• link this section in the "onboarding" popup message
• add new gif in readme for "basic" functionality (new colour blind friendly presentation)

Dev Triage

https://code.visualstudio.com/api/references/vscode-api#3120
https://code.visualstudio.com/api/references/extension-guidelines#notifications
https://code.visualstudio.com/api/references/contribution-points#contributes.walkthroughs

---

Original Ticket

Describe the bug
I went to the discussions / issues looking for documentation or other related issues. I was following the Python example in my own project, but couldn't figure out how to actually display the coverage – until I eventually realized I needed to "activate" the extension by using some of these commands in the command palette:

Since the extension does not auto-activate when installed, it wasn't clear to me if there was some additional configuration needed to get it going. Perhaps a simple Quick Start section in the README (or in the examples' respective README files) to indicate this would be helpful, since it's not immediately obvious what steps to take to actually display line coverage.

To Reproduce
Steps to reproduce the behaviour:

1. Install the extension
2. Generate coverage file (in my case, cov.xml)

Expected behaviour
Expect to see line coverage in tested file, but there will not be any without using one of the command palette commands.

[ryanluker]

@ian-h-chamberlain Thanks for submitting a ticket!
I agree that a better initial onboarding for the extension would be useful, I do hesitate to turn the extension on by default on install. Instead maybe some sort of light weight message popup in the bottom right explaining to go to an anchor in the readme to get started might be nice?

[ryanluker]

@mattseddon do you know if the information message api is the one that shows up in the bottom right corner?
https://code.visualstudio.com/api/references/vscode-api#3120

[mattseddon]

@ryanluker yep, you have three options for down in the right hand corner. window.showErrorMessage, window.showInformationMessage & window.showWarningMessage. You can convert these into a modal by adding modal: true to the options like this:

  window.showErrorMessage(
    'Something went wrong, please see the extension output channel for more details.',
    { modal: true }
  )

The flowchart shown in the notifications section of the extension guidelines has been really useful for me when deciding which notifications to display.

You also need to set a config options to be enable the user to not see the notification more than once (following the "Do not show again option" for every notification rule in the guidelines.

Hope this helps 👍🏻

[DannyDannyDanny]

Bump! I haven't been able to get the plugin working. I'm sorely missing a getting started or troubleshooting section 🥇

[ryanluker]

@DannyDannyDanny Thanks for the ping!
It will probably be quicker to open a new ticket or discussion to get assistance from myself or others that frequent this repo.

Usually the first thing I get people to do is checkout the example projects folder to see if any of those setups match theirs, https://github.com/ryanluker/vscode-coverage-gutters/tree/master/example.

These examples are what the integration tests actually use on a nightly basis with the latest vscode and insiders, so they should be solid.

[mattseddon]

@ryanluker could be a good time to implement one of the new walkthroughs.

:help-wanted: :good-first-issue: 😬

[DanielTOsborne]

I'm also having an issue getting this working, but my project uses gradle, which I know very little about (I'm not in charge of the project), so those examples don't help me. 😦

I'd also love to see more guide/walkthroughs.
As it is, I'll just have to look at the generated report manually, as I don't have much time to spend on setting this up right now.

[ryanluker]

@DanielTOsborne Thanks for the heads-up on Gradle being another option for the java folks (something that should be possible to add to the examples where we currently have a maven example).

@mattseddon Thanks for the heads up on the walkthroughs!
Definitely look like something we should add.