Welcome page experience for extensions

[xorye]

Hi, it would be great if there was an "onExtensionInstalled" activation event that would trigger when a VS Code extension is first installed.

Our use case for this activation event, is that we would like to display a welcome page for our VS Code extension when the user first installs the extension.

[rjstone]

Same here and exactly the same use case. Using "*" for this would be absolutely horrible. Best I can think of right now is to use onView with an extension's view if it has one.

(Good work on vscode BTW!)

[sandy081]

I do not think such an activation event will help because we do not always activate an extension immediately after installing. Unfortunately there is no way for extension to hook into for showing welcome page.

@kieferrm FYI

[rjstone]

I agree that for my case the real issue is "welcome experience". There's another issue that also falls into this category but is more about convenience of the extension developer. We're currently just using a markdown preview for our "welcome" document, but this has some drawbacks that could be addressed by adding some features to the markdown preview:

• A way to set the title on the tab to something custom rather than "Preview welcome.md"
• A way to set the security policy on the view so that command: URIs can work (for jumping to the settings panel, etc.)

Again I know I can just use a webview for this but I don't really need the full capabilities of a webview and it would be kind of nice if the markdown preview could be used like a webview. (Maybe there's a way to obtain a reference to the webview used by the markdown preview but if so I don't know what it is.)

Anyway, just something else to think about.

[sandy081]

@rjstone Can you please file a separate issue for markdown preview issues?

[rjstone]

Will do

[rjstone]

See #84886

It seems as though duplicate functionality would be needed to enable a simple markdown type welcome experience as the markdown preview module is unsuitable.

[rjstone]

Ok, well to start over, the end goal is to make sure the user is not totally lost after installing a new extension and get some initial configuration done. They might need some pointers on what needs to be configured for example, or even offered up some settings to configure. The way many people solve this now (take GitLense for example) is open a "welcome" page in a webview, then they just provide some quickstart howto instructions.

As for how to do it in the future I'm not sure.

But basically what I was attempting to solve is: user installs extension, seems lost and tells me "yea I installed it but don't know what to do" or "I installed it but doesn't work". So usually they either don't know something or they didn't configure a setting that was needed for what they expected.

Something better than just opening a HOWTO file would of course be great.

Also: A related experience issue is "major upgrade to existing extension" which could range from a "what's new?" document to some interactive process for migrating old data. Reason I think they're related is that installing a new extension and a major change to an extension are both major changes that happen when something is downloaded and installed.

[sandy081]

I see your point, but we open ReadMe of the extension when user installs the extension and expect this as a guide for the user given the extension author provides necessary information there.

The welcome experience what other extensions like gitlens does is helpful given that it requires user interaction to configure it which is not so easy to be surfaced in ReadMe.

But as said all your concerns are so valid and we will consider them when looking into this.

[rjstone]

Regarding the readme, the main dilemma with the readme is that since it's the main thing people see in the extension marketplace, there's a desire to prioritize "marketing" or feature overview information there and only put docs at the bottom of the readme. So someone could have to scroll through a few pages of screenshots to get to the documentation and might miss it. (I was somewhat confused by this when I first started using Atom.) Some things can alleviate this like linking to the lower section at the top but nevertheless some extensions have felt the need to display separate documentation in some manner.

I guess it's more of a new vscode user issue since eventually people learn to start looking toward the bottom of the readme for docs.

Anyway it's pretty minor stuff but something to think about I guess.

[miguelsolorio]

This should also account for when extensions are installed automatically via Settings Sync (#86285). Extensions should be able to differentiate between a first install and an automatic install.

[sandy081]

Assigning to May for exploration

[tboby]

I'd also really like this feature so I can provide a guided welcome experience for new users.

My extension is a language server for a video game scripting language. Most users have never used an IDE before, so they're brand new to VS Code. Further complicating this is that the scripting language requires some manual configuration and uses .txt files so requires a fiddly activation sequence.

As above, I can't make the README a detailed troubleshooting document as I need to convince amateur modders that they need VS Code instead of Notepad++!

[sandy081]

@misolori I remember you are working on mock ups for extensions welcome experience, hence assigning to you. Feel free to close this as duplicate if there is another issue. Thanks.

[sandy081]

From @alexdima:

IMHO, I think extensions have been using a pattern where they show a welcome screen on activate by checking for a memento and then saving the memento once the Welcome screen is shown. This worked well, but worked well only on a single machine.

I like the idea to introduce explicit API like e.g. ctx.canShowWelcome. Given the deep connection with settings sync and command line installation (e.g. extension installed due to devcontainer.json), I think you would be a natural fit to own this API. You would know better than me, perhaps this could be implemented straight-forward with global state syncing.

A special API that is provided by vscode has the benefit that we could explicitly set ctx.canShowWelcome to false when we really don't want to show welcome screens, like e.g. when using vscode as a git commit message editor, or reviewing a PR in codespaces, etc.

---

Additionally, it would be very nice (but largely out of scope for my specific ask here), would be provide the activation event (e.g. the reason) the activate method is getting called. For example, if you are getting activated because of a command, you might change your startup behavior.

This has been requested before in #44711 . See #44711 (comment) for more background on why it might not be desireable to define a closed set of activation reasons, since those reasons might grow over time. (2a, 2b were added later)

[sandy081]

I like the idea of providing some context for extensions while activating them. Instead of talking about welcome experience in the context, I would provide last activated version of that extension as the context for eg: ctx.getLastActivatedVersion. Based on that extension can control their welcome notifications. While following up with extensions with welcome pages or notifications, I have seen most of the extensions are using previous version to control welcome/update experience.

canShowWelcome might not be complete without having an API to show welcome also it will not cover updates experience that some extensions need.

CC @eamodio

[miguelsolorio]

We now have the getting started API that extensions can use and activate on install via the onWalkthrough:walkthroughID event. See the Python extension as an example: