#484: PWA Change logs

Visit on Github.

Opened Mar 12, 2020

Hello TAG!

I'm requesting a TAG review of PWA Change Logs AKA Version History.

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.

Further details:

  • I have reviewed the TAG's API Design Principles
  • The group where the incubation/design work on this is being done (or is intended to be done in the future):
  • The group where standardization of this work is intended to be done ("unknown" if not known):
  • Existing major pieces of multi-stakeholder review or discussion of this design:
  • Major unresolved issues with or opposition to this design:
  • This work is being funded by: Microsoft

You should also know that there is a WICG discourse thread here: https://discourse.wicg.io/t/proposal-pwa-changelogs/4290/8

And also some existing issues have been raised to the explainer github issues: https://github.com/MicrosoftEdge/MSEdgeExplainers/issues?q=is%3Aissue+is%3Aopen+label%3A%22Version+History%22 (filtered to Version History issues)

We'd prefer the TAG provide feedback as (please delete all but the desired option):

💬 leave review feedback as a comment in this issue and @-notify @stanleyhon

Discussions

Discussed Mar 23, 2020 (See Github)

Ken: I looked at that as well. It's kind of like you add to a webapp manifest a new entry and link to a resource - like a web site or could be "something else." I like the idea of one place to find the release notes. But if it's just html then it could look different from app to app. Maybe something like markdown could make more sense in this case. It might also be that you want to show the history in different formats. Most app stores just allow you to give it as text.

Dan: [in defence of having different look and feel for different webapp release notes]

Ken: but you want to have it in a trusted UI – you wouldn't want ads in it, etc...

Rossen: how is this different from other places where we use HTML?

Dan: some value in having uniform formatting rather than turning release notes into advertisements

Rossen: animated example at https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/VersionHistory/user-experience.gif

Ken: what i didn't understand from that GIF - is it trusted UI or not. At a minimum people should be able to provide different formats. Web site, markdown?

Rossen: I'm not sure why the full richness of html would be required here. If you compare this to a lot of the extension model type UIs, this is the closest I would compare with. I wouldn't compare it to native apps. Perhaps something like markdown would be sufficient here.

Ken: for accessibility purposes it might make sense that it works across ...

Rossen: Do we make the web apps more web like or more app like? From design review PoV the overall feature makes sense and having the mechanism of providing back the version history in a well formed format is a great addition to PWAs. I'm less keen on the details of the actual format.

Ken: but html isn't a "standardized format"- it's very flexible.

Dan: shall we push it back to them and ask them to consider the issues we've raised?

Rossen: i don't see a solid justification in the explainer itself.

Ken: I don't like they dictionary is called Resource – too generic.

Ken: also - if it's a standardized format like markdown you could implement search and make sure it works...

[debate between low-formatting change log and using a HTML web resource]

Ken: what about sharing a change log with my friends? (could always add a html link in addition to markdown and have a link to open it in the browser for easy reading and sharing)

Dan: I will write up some notes based on this conversation

Comment by @torgo May 27, 2020 (See Github)

We did discuss this in one of our previous TAG calls. To summarise our feedback:

If these change logs show up in trusted UI - like somewhere in your system it could open the door abuse and also people will expect it to look very similar in different contexts - and have very low level of formatting. HTML is very flexible but do you really need all the flexibility - as it might open the door to abuse and create unnecessary complexity in how it's displayed. We suggest starting with something like markdown.

Discussed Jun 22, 2020 (See Github)

Rossen: I will chase this up with MS people.

Dan: let's discuss at the plenary

Comment by @stanleyhon Jun 22, 2020 (See Github)

We've shelved this project based on feedback and may revisit it at a later date. Closing this review for now. Thanks for the feedback.