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.

[miguelsolorio]

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>;
}

[miguelsolorio]

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:

[miguelsolorio]

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.

[Tyriar]

@misolori really like the mockups, my only comments:

• A gift icon might be better than stars?
• The changelog may be very verbose and not get the details across quickly in the few lines allowed, some way of defining a summary for a version might be useful?

[miguelsolorio]

Reviving a couple of iterations as it has come up with regards to Getting Started.

Custom View

This would add a custom hover/popup that appears and links to the various content. Badges could help notify users when things have appeared.

Status Bar Item

Similar to the previous one but in a status bar. This intentionally looks different than the notification center to not be confusing. We could also add a toggle to move this to a custom view (from above)?

On the Welcome Page

This may add more visual noise to the page now that getting started is there but another idea

[RandomFractals]

I like all three. A setting to specify where we'd like them to appear would be great for devs to pick where they show up. Some might not like cluttered Welcome page. I don't use it as often. So, I would probably set it to show in the status bar, as my activity bar is a bit crowded too.

How do we contribute custom message to What's New?

Can you use last published release title from extension repository for those? So, we don't have to add anything extra to contributes in our extension package.json. I think there are already a few extra things we add to extension manifest contributes that are redundant and create extra work for packaging and publishing an extension.

As an example, I always try to add a short summary of what the release is about when I publish. Would be nice if vscode could just pull it from the github repository releases. Also, I think it would be a good convention for other extension developers to follow.

See Snippets Viewer releases. I think those one liners would look good in the new what's new message box: https://github.com/RandomFractals/vscode-snippets-viewer/releases

[PEZ]

How about a counter badge on the Extensions icon in the Activity bar? Hovering it could show which extensions are updated, some optional message provided by the extension and an optional ”Read more” button. The same text and button could be displayed in the extension entry for the entries that the badge counts. These entries could be sorted topmost also.

[RandomFractals]

@PEZ:

1. @misolori already has a counter on that what's new badge in the activity bar mockup.

2. I am assuming extension name link would take you to some new Release Note View or the Changelog tab in Extension Info View to see the details. So, probably no need for the extra "Read more" button there.

3. By sorted topmost, do you mean sorted by extension install count? Then we'll never see our extensions percolate there, if only 3 extensions are showing in those What's New boxes. I hope all updated extensions show there, not just a few.

P.S.: I am against the optional messages provided by the extension. I think it would be best to adopt some sensible conventions and pull your release title instead to avoid more messages adding to contributes per my note above. I don't want to code or update any new what's new document provider to see my extension release notes and title show up in those message boxes. :)

Extension configuration is already long enough with config settings, etc. We even created an extension recently vscode-contributions for everyone to use and document your custom commands, settings and snippets in a standard way for extension developers since we all used to do it by hand before.

[RandomFractals]

oh, I see what @PEZ is suggesting. Not adding new badge to the activity bar, but using Extensions button to provide all that what's new info on hover. I like that.

[PEZ]

Because the changeling is pretty boring to read. It's not a place for CTA:s and stuff. (And I did state them as optional, so no extra work if you opt out. Default could be changelog.md for all I care. (My release notes are automatically grabbed from my changelog and I rather keep it that way.)

[RandomFractals]

right. release notes are much better for that, if they can also pull in pics for display.

I used to just snap new charts and other things in Vega Viewer: https://github.com/RandomFractals/vscode-vega-viewer/releases

also, what's the point of keeping a separate CHANGELOG.md and copying it over to your release for release notes. I think that's redundant and brief release summary is better in my opinion, based on some good OSS repos I've seen and use too.

[alefragnani]

Hi @misolori ,

I like all three ideas, but personally I would keep only the Activity Bar and the Welcome Page choices. The toogle to choose between Activity Bar and Status Bar is clever, and could be added, for those that like thing on status bar 😄

Like @RandomFractals and @PEZ commented, I'm not sure how extensions would provide the message displayed, but I expect not to be from package.json. Maybe some API like @GustavoASC commented.

I understand this What's new feature as a way to extensions that want provide this information when its extension updates, right?. If that's the case, those that choose not to provide a message/contents, wouldn't appear here.

I'm not sure a read more button is necessary, since the original mockups already shows the Release Noted/Change Log being opened when you click on the extension's message.

I prefer not using the Extensions view because it already have so much information, and opens with different filters (depending on you current workspace - remote/untrusted workspaces). Also, the user would need to scroll to find the extension.

Thank you

[miguelsolorio]

Thanks everyone for the feedback, this is very helpful! In terms of adding this into the extensions view, we did consider this but the extensions view is already busy and the badge is used for when extensions are updating, so there could be a clash of badges there. That's how I ended up trying out the custom view version, which will be toggleable.

For enabling this, this is something that we've yet to discuss in depth but there are a few ideas:

• We can make it opt-in where users will have to add a certain flag in the package.json (preferred)
• We can turn this on automatically for all extensions that use the changelog file (this would make busy)

And in terms of deciding what string + content is used here and where it would go, a few options:

• You can provide a text string, or use the first few lines of the Changelog file (if applicable), or we'll use a generic string like {Extension}: Updated to version {version}
• You can either link to a markdown file or the Changelog tab on the extension view

In terms of where this would appear, my comment was about allowing the user to configure the placement. We'd probably start with either the custom view or status bar and then have a command to toggle the position, just like other views.

The API specifics haven't been fully discussed as we're just exploring what the design could look like and making sure we fill any gaps with either options, so we really appreciate all of the feedback!

[RandomFractals]

badges aside, I think it would be helpful to have new Releases view tab in Extension Info to view releases, install older versions of an extension as provided by Version History in VS Marketaple now, and have ability to view Release note summaries.

Also, I don't know if adding another opt-in flag is necessary. We already have a lot of them for extensions. Why not do it by default? and use release title for the update message line without requiring extra config or docs update?

[alefragnani]

Hi @misolori,

For enabling, if you stick with an opt-in via package.json, I would ask for a simpler approach, like adding a new entry to the new "capabilities" attribute, so the extension would say "I want to be visible in the What's New icon"., like:

    "capabilities: {
        "whatsNew": true
    }

But for the contents, even the description shown in the What's New icon, should be provided by the extension instead of being part of the package.json, avoiding to replicate the api-proposal used in the Getting Started content issue (#119097).

For those extension devs that just want to be visible in the icon and don't provide the content, you could use that "generic approach" you commented to the description, and open the Changelog.md on click.

Also, I wouldn't mix Changelog with What's New/Release Notes, mostly because I see as two separate things, with two kinds of consumers

What's New / Release Notes

Consumed by end users which are interested in rich, pleasant to read content. They want to know what has been released, and how it looks and works. The same VS Code users which keeps the Show Release Notes checked, and read it from top to bottom (that's me 😄 )

Changelog

Consumed by "devs" which are more interested in issue tracking. Maybe they want to contribute to the project, or simply want to know how many bugs has been fixed. (that's me, sometimes 😬 )

Looking at the Getting Started content issue, I didn't understand why it has been decided to use the contributes section in package.json approach instead of the extension itself providing the data. Maybe because you need to have access to the extension's content even if the extension is not activated yet, but I really don't know. I didn't find many information about the decisions/discussions about that topic. Maybe I'lll ping there to understand.

Thank you

[anburocky3]

Any updates regarding this?

[kakty3]

@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:

I see you click on See more... link and extension's Changelog page opens. Could this behavior be achieved now or is it just mockup?

[miguelsolorio]

@kakty3 these are all mockups so they are design explorations

@anburocky3 no updates yet besides the design explorations posted. Once this gets added to a milestone we'll update this issue with next steps as there are a few scenarios to still work through.

[ruiminwang]

Hi all, Currently, is there any good way to pop up the changelog once our extension is updated in customer's VS Code?

[vscodenpa]

We closed this issue because we don't plan to address it in the foreseeable future. If you disagree and feel that this issue is crucial: we are happy to listen and to reconsider.

If you wonder what we are up to, please see our roadmap and issue reporting guidelines.

Thanks for your understanding, and happy coding!

[unikitty37]

Could you at least ban extensions from popping open their changelogs without explicit user consent? Most of the time, I don't care — and I certainly don't want to have tabs suddenly open when I'm trying to concentrate on what I'm doing…

[NatoBoram]

Here's another use case:

• Add an option to disable the "What's new" tab alefragnani/vscode-bookmarks#175

Getting rudely interrupted during flow effect by an update pop-up advertisement is really annoying.

[working-name]

Example of how rude extensions get with this "feature":

Hey @sandy081, we see you've commented in a community issue! Did you know you can do more with your comments? Upgrade to PRO and then you can do this:

• tag your comments with pretty little yellow flowers!
• copy paste your comments wherever you want!
• get unlimited badgering by any number of random people, publicly!

Did we mention we have a discount?! A whopping 20%. So why wait?! Get the upgraded extension bugging mode. Continue using VS Code and get bugged, interrupted, and have ads shoved in your face! On your own computer! When you're trying to be productive!

Did I make my point or should I pester-tag you in every damn comment you ever leave from this point on?

[domenic]

I'm sad that this issue was closed, and that #112494 was closed as a duplicate of it.