Epic: In Product Changelog - VS Code only

[loujaybee]

Context	Currently, when new changes are released in Gitpod, users are not always aware of what has changed and why. For Gitpod, we have the Gitpod changelog, but the changelog can be easy for users to miss. This epic is to implement an in-product solution to help users become more aware of changes that are made to Gitpod.
Owner	Product - @loujaybee / Tech - @mustard-mh
Value	Users are aware of product changes that are made to Gitpod, so that they understand: why something might have changed, and can keep an eye on any new features that they (the user) can start to take advantage of. The in product changelog will also act as a way for Gitpod to showcase early features to users for their feedback.
Acceptance Criteria	- When a changelog is released, a user is made aware via an in-product experience
Growth Area	N/A
Persona(s)	- All Gitpod users
Hypothesis	An in-product changelog entry will make users more aware of the product changes to Gitpod, but more engaged in providing feedback, and ultimately feel like Gitpod is rapidly evolving and updating.
Measurement	TBC
In scope	- Testing of main VS Code extensions
Out of scope	- Providing "smart updates" e.g. updated since the user last visited (e.g. show only the latest changes)
Complexities	TBC
Latest Update	01.03.2022 - Epic moved to Q2 2022, reasons discussed in comments

Related issues:

• Update changelog template (for pre-release features) #11622
• Align in-product changelog version with self-hosted installation. #11641
• Filter the self-hosted changelogs from the in-product changelog #11675

Public FAQ

Will we also add changelogs to JetBrains?

Yes, but as part of a separate issue in future.

Will we also add changelogs to terminal / CLI?

Yes, but as part of a separate issue in future.

Where is the state stored to hide/show the changelog?

In both VSCode browser and desktop, we store it by VSCode built-in API ExtensionContext.globalState https://code.visualstudio.com/api/references/vscode-api#ExtensionContext.globalState

Will it show the latest changelog, or all previous?

Latest only, if users want to know all previous changelog, they can visit https://www.gitpod.io/changelog

Why did we choose to do the changelog in the IDE rather than in the dashboard, or CLI (for cross-IDE support) for instance?

This is a first iteration, and follows the same pattern as VS Code release updates, we can review how to integrate also into the other editors / aspects of the product soon. This should at least surface the changelog to a very large % of the Gitpod userbase.

Internal FAQ

Will the feature work on self-hosted Gitpod? Are there any considerations?

As it's implemented in the vscode extension it will show the latest changelog not the one from self-hosted installed version, there is an issue to address this #11641 so that self-hosted VS Code users only see the version related to their self-hosted installation.

Is there a way to "bring back" the changelog once it's dismissed?

Yes, there is a command palette action for that.

Does the feature filter out the dedicated self-hosted changelogs?

TBC

How does the feature interface with the existing Changelog on the website?

There are some dedicated endpoints in the website #2405 which expose the changelog information, which is then consumed and shown by VS Code. We strip any svelte specific information to ensure it's valid markdown

[gtsiolis]

Cross-posting #3956 (comment) for reference and visibility. See also #3956 (comment):

In the past, we've been using this modal for blocking workspace start so users would see that either 🅰️ by visiting the dashboard or 🅱️ by trying to open a workspaces directly from a repository via clicking the Open in Gitpod button, even when prefixing the repository with gitpod.io/#.

Ideally, we could define 🅰️ which of these udpates would be blocking that require users to confirm or dismiss and 🅱️ which silently populate this new what's new section where the red dot signifier could help inform the users about new updates. 💭

[gtsiolis]

A possibly good MVC (minimum viable change) step could be to continuously and reguarly update the changelog and simply link to the changelog from the dashboard near user profile menu links. 🌔

[loujaybee]

Given the other ongoing priorities for the IDE team (internal link: [1] - mostly a narrative on current roadmap items) I'm going to move this deliverable to Q2 for now. This could be achieved in a small solution, and could be picked up in the mean time. Alternatively, if urgent, I think this is also something that could also be picked up by web app (CC: @jldec)

[mikenikles]

FWIW, I like Notion's "What's new" dialog.

Screenshot

[loujaybee]

Linking internal conversation regarding breaking change communication.

Linking internal RFC on changelog process.

[JohannesLandgraf]

To cater our cross-editing experience strategy it might be worth considering showing the Changelog as terminal output (we can look at Changelog updates surfaced via CLIs as inspiration)

[loujaybee]

Relates to:

• Make better use of the splash screen #9423

[loujaybee]

Moving to Q3, the team made some internal processes changes for the changelog process: https://gitpod.io/changelog to push updates more frequently, now that those updates are embedded we can look to pick this up again.

[loujaybee]

Two self-hosted related issues added:

• Filter the self-hosted changelogs from the in-product changelog #11675
• Align in-product changelog version with self-hosted installation. #11641

[loujaybee]

Closing, as now implemented in VS Code, we will need similar functionality adding also to JetBrains, and to the CLI. For more details see the changelog entry:

https://www.gitpod.io/changelog/new-ports-explorer-changelog-view-and-connection-improvements-for-vs-code#latest-changelog-view-in-vs-code