Improve initial debug / run experience

[isidorn]

Currently setting up debugging is not an easy task for new users. Due to that we decided to create this issue where we can discuss how to make it easier for users to start debugging / running their programs.

A first proposal:

1. Replace the debug icon in the activity bar to be the play icon. This should make it easier for users to discover that they can also run their program via the debug flow. It can be either a simple play icon, or a play icon that would somehow show that you can also debug (e.g. small "bug" sitting in the corner of the play icon).
2. CallStack, Variables and Watch Expression view do not really have much value while a user is not debugging. Due to that we will only show them while the user is debugging and we get extra space which we can use for rendering a wizard-like UI, e.g. buttons like the one in the explorer:
   
   

These "buttons" could cover these use cases:

• Run Current File (or Run Active File)
• Debug Current File (or Debug Active File)
• Configure
• Install Additional Debuggers (maybe not needed)

While showing the button UI we would not show the launch config drop down and the gear icon (because this duplication would be confusing).

fyi @chrisdias @misolori @fiveisprime

[miguelsolorio]

Here's an initial mockup that has the proposed items:

We do have a proposal to add a secondary button style, so that could be used here as well.

[chrisdias]

I like it. Do we need "You have no launch configurations." text? I suspect the term "launch configurations" doesn't mean anything to many folks, so maybe something that is descriptive of what you can do rather than what you don't have would be more helpful. I don't have a good suggestion for text right at this moment though :)

[miguelsolorio]

I agree that the text isn't very descriptive, though I'm not sure what other text would be helpful. I did have another idea where we could prompt the user to create one, but I'm not sure if that would be useful as launch configurations are a new concept for most users:

[fiveisprime]

Another thing worth mentioning is that "...current file" isn't always accurate. I have a model open and launch the debugger with no config and the express app is correctly launched rather than trying to exec my model.js.

The language can be much friendlier, something like "Run this app."

Can the editor be smart about what's in the workspace? For example, package.json tells us a lot about the app including the name and the type of app (along with how to run it, but I believe that's already detected). We can determine if this is an app or module.. or maybe a combination of things if there are multiple pacakge.json files. If I have an Angular app and a Function app (with the Functions extension installed) show both of those. I actually have this kind of app here: https://github.com/fiveisprime/apm

The root ./package.json is the Angular app named "apm" and there's also ./functions/package.json named "functions". Show me each "app" along with what debugger is able to run it:

• Run "apm" (Node.js)
• Run "functions" (Azure Functions)
• Run all (okay, maybe this is risky 🤣 )

I realize this will get out of control if we try to handle every case so maybe the debuggers can contribute this. They would need to contribute the markers to "announce" they can run something in the current workspace.

Doing this may prevent users from ever having the directly deal with launch.json unless they really need to do some custom shenanigans. I don't think that's a goal of ours though so maybe I'm creeping a little.

[isidorn]

Thanks you for your feedback, however we have already discussed both these concers at the UX meeting last week.
I should have a working version this week and then you could provide more feedback!

[isidorn]

Thanks again for the feedback. Here's a very first rought version of this and I would love to get feedback.

This new view I call the start view. So please note:

• The Start view is shown when you do not have a launch configuration and while you are not debugging. Which means as soon as you setup launch.json, or start debugging the other views come in its place
• @weinand and me decided to call the actions Debug Code and Run Code. @fiveisprime unfortunetly we do not have extension contributions which would allow us to know what will they launch (potentially giving a better name). Debug App and Run App also sound great, but do not fit all use cases
• I put the Debug action first, since that felt more honest (all our UX that appears is tuned towards debugging not running)
• Feedback on the text would be very welcome. Current one is "You have not yet configured launching. For a more complete debug and run experience create a launch.json"
• @weinand has suggestions to introduce more text, but I am a bit worried that it might scare off users
• Title area has the folowing text Debug: Start and does not show the actions to avoid duplication

In case somebody is hot to try it out in action, here's the PR.
#85398

Also fyi @eamodio @joaomoreno @sana-ajani @roblourens @connor4312

[miguelsolorio]

FYI @qubitron

[roblourens]

I like it. It would be cool to be able to contribute an action to it too. Something that you might not have seen yet is that with the new node DA, we have the ability to start arbitrary node processes in debug mode more easily, for example it has a "debug terminal" where vscode will attach to any node process started in that terminal. So we need to figure out how to expose that capability, and a button for "start debug terminal" might be cool.

[joaomoreno]

I have mixed feeling about the Code suffix in the button labels, since that's our product name, especially capitalized. Maybe simply Debug and Run? Maybe prepend some icons to the button labels?

You're making it It feels awkward when starting a sentence with the word you. How about:

There are no configured launch configurations. For configuring the Debug and Run experience, create a launch.json file.

[isidorn]

Thanks for the feedback.

I will improve the text. And for now we will go just with Debug and Run.
I am also thinking of renaming the viewlet from Debug to Debug & Run.

After discussion in the standup we came to the conclusion that it would be nice to make this a contributable menu, and that all extensions can contribute there. We would have to enforce when context on top of these contributed commands just so the view does not end up being a jungle. For example when activeFile is python add the python commands.
An open question is how these contributed commands would look like, would it also be a blue button, or is there a ... affordance which when clicked shows all the contributed commands.
However making this view extensible I just created a seperate issue and we can continue the discussion there #85548

I think it is fine to show these 2 + 1 (debug, run, configure) commom commands for every debugger, and that via these contributable commands every debugger can customise the experience.

Another feedback was that even if I have a launch.json it might not be useful to show variables, watch, call stack while not debugging. I fully agree with this, however I would also tackle this independently from this issue

fyi @jrieken @aeschli

[chrisdias]

I don't think you even need to say "There are no configured launch configurations", I think it is implied.

How about simply To specify how to run and debug your code, create a launch.json file.

[qubitron]

I wanted to add that the majority of users we see in user studies ignore the side bar and look to the menu items, they gravitate towards text and the menu bar says "Debug".

So we should probably take a look at how the menu bar is used as part of this.

[isidorn]

Based on the feedback I have polished the view and this is the state of things now:

1. Renamed the viewlet from Debug to Debug and Run
2. Changed wording as suggested
3. introduced a context key debugUx which can be default or simple. The extensions can use this context key when contributing views and actions.
4. Renamed the Debug: Start Without Debugging to Debug: Run (Start Without Debugging) in the command palette and just Run in the top menu.

@qubitron are the users in your user study first time users? If yes, that would explain why they look at the top menu, since we have noticed that brand new users use the menu bar as a way to explore the product. The menu bar can be renamed, however for now I have just done the action rename 4) I did not rename the top level item for width concerns. For follow up on this can you please create a new issue

There were ideas to add text before the buttons as well that would explain the state better. For now I did not add this, to not have too much text and scare of users. However I am open for suggestions.

Follow up work for next milestone is #85548 and we should try to get feedback from debug extension authors how they would like to customise this experience.

[qubitron]

I like where this is headed, we should run this through user tests to get feedback.

@isidorn to answer your question yes, these are first time users to VS Code.

Visually for the Debug menu I think it would look better to have Run be the first item, then followed by Start/Stop/Restart debugging, though I also see why it makes sense for Start Debugging to be first in the list.

fyi @luabud @Anapo14

[eamodio]

I really like the changes, but I think the view title should be Run and Debug as it feels more natural (because you run and debug -- like in the To specify how to run and debug you code...).

Also I agree with @qubitron, I think the Run menu item should be first. Also imo the Run button should be first too.

[isidorn]

After some great feedback from @weinand we fine tuned the experience (especially for corner cases). Here are some examples:

1. User has a folder opened and has a Python file opened

2. User has a folder opened but no editor opened, or has some file which no debugger exists for (for example a .json file)

3. User has no folder opened but has a Python file opened

4. User has no folder opened and has no file opened

Feedback is very welcome!

[isidorn]

We can rename the view to be Run and Debug - this makes sense to me. Let's see what others think.

We will not change the order of the menu items to not screw up muscle memory of users who are used to the current ordering. Also keeping the order makes it clear for the user that Run is actually Start Without Debugging from before.

[eamodio]

@isidorn 👍 on both! Maybe for the Run menu option -- call it Run Without Debugging?

Also minor, but maybe replace To further configure the... with To customize the...?

[isidorn]

Run Wihtout Debugging sounds like it may scare new users. I like the simple Run. But I know @weinand had a similar suggestion

Yes! I like the customise wording suggestion. Shorter and cleaner.
Further suggestions on wording very welcome!

[eamodio]

Yeah, true. Run is simple and clear.

[eamodio]

I'm not sure I like the * with Python suffix. Part of me likes it as it can be helpful for new users, but how would it work for multi-root folders - where you could have multiple languages? Or just a folder with more than 1 language?

What happens if you have a launch.json configured -- how will that change this experience? For example, it would be cool if there was a way to signal from a specific launch config that it should show up as a button. Or maybe at least, a signal that a specific launch config is the default "debug" and/or default "run" config?

Also maybe the buttons should go along with the menu labels? So Start Debugging and Run?

[qubitron]

Agreed I'm not sure the "with Python" adds much here for the implementation complexity it might bring. I could also see it being confusing "what do you mean with Python? how do I use python to debug something?"

[weinand]

Just a clarification:

Today VS Code does not support generic "Run" functionality!

What we currently support is the optional "noDebug" attribute of launch configurations:
VS Code's "Run" is basically the same as "Debug" but with a "noDebug": true added to the launch configuration.

If a debug adapter supports this hint, it will launch the debuggee but disables debugging.
If a debug adapter ignores the hint, "Run" is identical to "Debug".
If a debug extension is not smart enough to work without a launch config, neither "Debug" nor "Run" will work.

VS Code does not know whether a debug adapter obeys the "noDebug" hint. So the VS Code debug UI will switch to debug mode and show a debug toolbar in any case.

With these details in mind, I'm a bit reluctant to make "Run" a prominent first-class-citizen in the VS Code UI. Today you never know whether "Run"

• works at all
• is the same as "Debug".

I suggest to treat "Run" more as a variant of "Debug". That's the reason why I prefer "Run without debugging".

Before we can make "Run" a prominent first-class-citizen, we need to improve the extension API/Debug Adapter Protocol so that a debug extension can clearly state that a "real Run" is supported. In this case we should consider to make VS Code show a different UI, e.g. one without a debug toolbar.

/cc @isidorn

[isidorn]

This makes perfect sense. As a follow up item to improve the run experience I have created #85759

And I agree, for now let's go with the safer "Run Without Debug".
Also for the name of the viewlet we will keep the Debug and Run. We can change the order to Run and Debug when we improve the Run Experience and when we get an icon which will resamble running also (currently we will use the bug icon).

@qubitron with Python does not introduce any implementation complexity. Based on the active file VS Code knows which adapter is interested in it, if there is only one adapter then vscode will use the title Run With {Label}

@eamodio for now we are not showing this view if you have a launch.json setup. Once we decide to open that door we can continue the discussion in that direction. Start Debugging and Run I do no like as a pair, it should be Start Debugging and Start Running. I prefer the simple Debug and Run.

Thanks all for feedback!