Allow specifying prompt prefix via Environment variable collection

[karrtikr]

export interface EnvironmentVariableCollection {
    /**
     * A string that will be prepended to the existing prompt in the terminal. Keep it short and only use it if
     * it's really needed, as it modifies all terminals, even those not related to the extension.
     * 
     * Note this only applies if shell integration is enabled.
     */
    promptPrefix: string;
}

The idea is to use shell integration to apply this parameter. This can be used by Python extension to indicate an environment is activated in Powershell or fish where there is no other way to set the prompt.

[Tyriar]

API sync summary:

• This is an API that is dangerous to our UX as it could be abused very easily
• @karrtikr post why this is important to the Python extension
• @Tyriar post all the alternatives we've considered
• Maybe bring to UX sync to discuss the issues

[Tyriar]

There's been a lot of behind the scenes discussions on this, here's a summary of what we've considered:

• A special private VSCODE_PROMPT_PREFIX variable that could be contributed via EnvironmentVariableCollection API that we would only allow the Python extension to use
  • This is essentially just a forever proposed API but would require vscode-python to be mentioned in core (soft layer breaker).
• A "forever proposed" API like onDidWriteTerminalData
  • This is an option that would prevent abuse, but we generally don't like these APIs.
• A new class of API that would require us to allow extensions to use
• Allow extensions to contribute a variable that can be used in the terminal title
  • This would just show something like "conda" next to every terminal
  • This could only show for the active one, but the terminal tab title/description doesn't do that so it would be another special property like a tab detail

[karrtikr]

Adding a couple more options we discussed:

• A bell icon in terminal tab that can motivate users to hover over the terminal tab, where we already have a description stating env is activated, similar to:
  
• An issue with the above is that the bell/warning icon shows up next to all terminals, and we don't have a centralized location for all terminal related notifications. An alternative could be having such a icon there in case there are notifications:
  

[karrtikr]

@karrtikr post why this is important to the Python extension

Terminal prompts are generally used to indicate whether a Python env is currently activated in terminal:

There's generally a shell specific variable which can be set to do this, but powershell and fish have a concept of prompt functions instead which have to modified by running a script instead to set the prompt.

We're fine with fish not indicating if an env is activated given it's not used as much, but powershell is the windows default which is slightly more concerning.

[Tyriar]

Since we had differing opinions, we brought this issue of prompt prefix vs inconsistent environment activation to the UX sync, to get a final decision and commit to it. Here's what we discussed:

• The prompt prefix is too powerful and could be abused to easily, so it's not an option
• We want to adjust a Python user's expectations, so this really only needs to be a one-time thing
• Since user only needs to see this once, a notification, despite having problems, is less noisy than showing something for every terminal

So the final decision is:

• When the Python extension activates, it will listen to onDidOpenTerminal and show a notification explaining that the Python extension handles activation
  • The notification would show up once per session/window
  • The notification will include a link to docs that go into more detail on how environment activation works and how to configure it (eg. explain that you can switch to the command running method once the default method is switched)
  • It will have a do not show again button that will prevent it from showing again, this decision should be synced via settings sync to minimize a user who acknoledged it from seeing it again
  • Since it's listening after extension activation, this should prevent a notification showing up on startup or after a syncing extensions
• It's up to the Python extension whether we want to attempt to show the activated environment in the prompt when it's possible by only setting environment variables (I'm guessing we will do this)

@karrtikr can you create an issue to track this new work for the Python extension and we can then close this issue out.

[karrtikr]

Thanks, created microsoft/vscode-python#21793.

[amunger]

The notification did not clear up this change for me - I saw that the prefix was missing and immediately concluded that it was broken.
maybe if the notification had an explicit "we're not showing (.venv) anymore", but the current message did not help change my expectation.

[karrtikr]

We had planned something similar earlier: microsoft/vscode-python#21793 (comment)

but did not go with it. Do you think this helps, or should we explicitly add the name of current env (.venv) in this one-time prompt?

cc/ @cwebster-99 @luabud

[karrtikr]

Here's what I'm currently thinking:

Python extension automatically activates all terminals using the selected environment, even when the name of the environment is not present in the terminal prompt. Learn more.
[ Don't show again ]

We can move "You can hover over the terminal tab to get information about the activation" into the "Learn more" doc.

[karrtikr]

If we add the name of the environment:

Python extension automatically activates all terminals using the selected environment, even when the name of the environment (.venv) is not present in the terminal prompt. Learn more.
[ Don't show again ]

[amunger]

Those changes would help, especially adding the environment to catch my eye since that's what I look for to see if an env is activated.

[luabud]

The notification change makes sense to me! And the idea is that it'd show the name of the currently selected environment, right?

[karrtikr]

Yep: