Vscode: What's new icon/UI for extensions (and future API)

[fiveisprime]

In the extension authors call today, it was confirmed that extension authors want to share the following items when extensions are updated. We also know that customers don't want to be bombarded by welcome/update pages opening when extensions are updated.

• New features
• Fixed issues
• Features/UI that moved
• Images or gifs showing how new features work
• Guided tours of new/updated features

With that in mind, it's possible to alert customers that extensions have been updated and allow them to go as deep as they want, whenever they want, to learn about new features and fixes.

Provide a new UI element in the activity bar of a "gift" or something similar to indicate extensions have been updated.

The badge count would indicate how many extensions have been updated and clicking the "gift" icon would show an overlay with a short blurb taken from the extension changelog (automatically taken from the .md).

Firefox does something like this:

This allows customers to mark items as "read" to remove the badge count; out out of future update notifications; and click into the "learn more" link to go into the extension's changelog in the extension view.

Showing the changelog could be automatic, but in future iterations we could create richer experiences such as overlays or guided tours. This would require an API that extensions would expose to launch into the update experience.

[misolori]

Here's a quick mockup of an idea that @eamodio and I have been talking about where we could add a custom entry in the status bar for this "What's new" section that has content similar to notifications but relative to extensions and features:

We could also provide for extensions to provide links/commands for custom content that opens on the side (as an idea)

[GustavoASC]

@misolori great job! I like this UI. It's really intuitive.

We could provide an API to show a WebView, run a command or return the URI of a markdown file with documentation for the new features. Something like this:

export namespace extensions {

    /**
     * Registers a provider to supply extension documentation.
     * 
     * @param extensionId extension identifier in the form of: `publisher.name`.
     * @param provider provider implementation to supply docs for the given extension.
     */
    export function registerExtensionDocsProvider(extensionId: string, provider: ExtensionDocsProvider): void;
}

/**
 * Provider which supplies documentation for a given extension.
 */
export interface ExtensionDocsProvider {

    /**
     * Returns true whether the extension provides documentation for the specified
     * version.
     * 
     * @param version Version to check whether the extension provides documentation
     */
    hasDocForVersion(version: string): boolean;

    /**
     * Provides documentation for the specified extension version.
     * 
     * This method is called when user interacts with `What's New` pop-up, 
     * tipically shown when the extension is updated.
     * 
     * @param version Version which documentation will be provided
     * @returns A thenable that resolves to a command name, a Markdown URI or a Webview
     * which will show documentation details for the given extension version
     */
    provideDocResource(version: string): Thenable<string | Uri | Webview>;
}

Besides, VSCode would need to store a list of versions for which the docs have already been presented to user.

[GustavoASC]

Here is a different idea of API function which already receives the extension version related to the provider:

export namespace extensions {

    /**
     * Registers a provider to supply extension documentation.
     * 
     * @param extensionId extension identifier in the form of: `publisher.name`
     * @param version extension version for which documentation will be provided
     * @param provider provider implementation to supply docs for the given extension
     */
    export function registerExtensionDocProvider(extensionId: string, version: string, provider: ExtensionDocProvider): void;
}

/**
 * Provider which supplies documentation for a given extension version.
 */
export interface ExtensionDocProvider {

    /**
     * Provides documentation for a given extension version.
     * 
     * This method is called when user interacts with `What's New` pop-up, 
     * tipically shown when the extension is updated.
     * 
     * @returns A thenable that resolves to a command name, a Markdown URI or a Webview
     * which will show documentation details for the given extension version
     */
    provideDocResource(): Thenable<string | Uri | Webview>;
}

[misolori]

A couple more updates/ideas:

Instead of trying to create a separate item for this info, what if we combined these messages into the notification center and provided for ways to filter between the content (All, Notifications, Updates):

And what if we also showed this in the welcome screen where there would be more visibility for these items:

Here's a flow for how the interaction would work:

[misolori]

After feedback from the team, there's a strong desire to have these items separate from notifications and to have a dedicated area for them. So the updated proposal is back to the original one where we have a single "Updates" entry in the status bar that shows a list of extension updates and core features that can either link to a markdown preview or extension changelog. There's also discussion about bringing this directly into the Welcome screen for greater visibility:

[RandomFractals]

yeah, I like this last revision with dedicated updates page & changelog display for more info.

should work really well for those of us who publish changelog.md for ext. updates.

[RandomFractals]

tbh, I would like to see you incorporate some of the UX from @alefragnani's what's new view:

https://github.com/alefragnani/vscode-whats-new

I would like to see sponsor, review & contact links to be displayed more prominently on ext. updates view.