[Proposal] PWA Changelogs

Full explainer available here

Introduction

When a new version of a piece of native software rolls out users are typically made aware through a notification in their operating system or the app store they use. The web—in contrast—is evergreen, meaning that software built atop it is always up to date. Because of this, there is no formal “moment” in which developers of web-based software can inform their users of what’s changed with their software from release to release (e.g., new features that have been added, which bugs have been fixed). Providing a standardized means of surfacing version history would enable developers to surface this useful—and sometimes crucial—information.

Proposal

In the existing manifest.json this proposal would add a new subtree that contains information about where the PWA developer presents new changes to the PWA.

If the developer decides they want to leverage this feature, they would include the relevant information in their manifest.json and user agents would present this information.

The specifics and syntax of the proposal are available in the explainer linked above.

What’s the benefit of adding this to the Web Platform vs allowing for apps to implement it themselves, potentially by using third party libraries that abstract it away? Discord is an example of a well-known desktop app and website that implements changelogs using existing web technologies (LocalStorage, etc). This feels like more of a framework-level feature that could be implemented in many different ways by different JS/HTML frameworks then something that needs to be a platform-level feature.

Hi Nightpool,

I see this as less of a Web Platform vs apps implementing themselves and more as an alternative if PWA developers want it.

Adding this would not preclude app developers from doing anything they desire and is a fully optional feature. In the discord example, if discord were to be a PWA they could choose to continue to use their existing change log feature.

As for some reasons why this would be good to have in the platform - here are some reasons I think it is valuable to have in the platform despite PWA devs having a BYO alternative if they desire.

1. The platform can show indicators/notifications/alerts in the platform UI that the web content otherwise has no access to.
2. The platform is in charge of keeping track of local PWA information and updating it. If a PWA developer wants to publicize an update to any of this information they currently have no reliable way. If the PWA developer publicizes it in the web content, they do not have an assurance the end-user is actually using the update to date PWA. With this feature, the changelog information is also the responsibility of the platform - thus they stay in sync by nature.

I think it’s worth clarifying that Pt.2 is something that discord does not need to deal with because discord stays ‘always up to date’. A PWA is different in that while the web content can always stay up to date, the state that the platform keeps for a PWA does not behave this same way.

3. Another reason I think it would be valuable to have this is that all PWAs feel like part of the same family of app. Having a platform standard way of doing change logs mean that it is easier to eventually have a type of overview like what you would get with Google Play store/iOS App Store “all up apps view”. For example, currently Chrome and Edge have chrome/edge://apps view - which is sort of like this “all up apps view”.

It would be possible to show all recently updated apps in this view and the changes devs want to publicize with this changelog feature. This would not be possible with a change log that is implemented in app in the web content (however devs are free to go this route if desired).

This also serves as a good way for developers to surface significant feature enhancements up to app stores that consume manifests (or will start soon) for their PWA listings. It would require no additional effort on the part of the developer to keep their listing up-to-date.

TBH I’m not sure this is a problem that needs solving. When making a PWA there is often has a website to accompany it, and the website is a good place to post update notes too. There are also already techniques for ensuring PWAs are automatically up-to-date, and when it updates, it’s a good time to notify the user and provide a link to a changelog. All this is exactly what we do already.

Could you elaborate on how you currently keep PWAs up to date? It seems to me like updating is a bit of a neglected topic within PWAs prompting discussion such as https://github.com/w3c/manifest/issues/446. In Edge and Chrome, PWAs can’t be updated until the user reopens them - which means sometimes the web content won’t have a good way to know if the PWA has been updated or not.

Perhaps a point of ambiguity here is that, I think there are ways for some parts of PWA code to update (e.g. service-worker, or updating the actual live webpage JS/HTML/CSS). However, a full update on Chrome and Edge including manifest.json updates require a reopen.

I am also curious about how you are currently solving this problem end-to-end. What mechanism are you using to notify the user and how do you link to the changelog?

Basically this proposal at it’s fundamental level is simply providing a place in the manifest.json for you to put update information should you choose to use it. My intention is to then proceed to implement UI features to surface this information to the user within the browser. I think this would already be a better experience than using say a HTML based popup or other web content based notification.

If the SW updates to a new version in the background, it posts a message indicating an update is available. Then we show a popup saying “A new update is available! Click here to reload”, which just does location.reload(), and then they’re on the latest version. If they don’t reload, they just keep using the old version until they next happen to reload themselves (including e.g. closing the tab and coming back later).

Once we’ve detected that they’ve updated, we show another popup saying “You’ve updated to the latest version! Click here to see the release notes”.

I didn’t think we were particularly special in doing this, I thought it was a pretty standard way of doing things.

Thanks for clarifying @AshleyScirra. I hadn’t considered that and it does sound pretty effective.

@AaronGustafson and some other folks here on Edge discussed further and think there is still some interest for something like what we are proposing here (See Aaron’s twitter post here). Since what we’re proposing here won’t effect what you’re already doing - I think both ways could coexist.