Ghost: Update Notifications 2.0

[ErisDS]

A little while back, we added a system to Ghost which regularly asks Ghost.org if there's a new version of Ghost available.

Ghost.org replies with a little bit of JSON like this:

{
  "version": "0.5.0",
  "next_check": 1427366737
}

This tells Ghost what the current version is, and when it is allowed to ask again.

Inside of Ghost, this is wired up to our notification system, and if the version number goes above the current version of Ghost, a special notification is shown at the top of Ghost, on all pages, which doesn't go away until the blog is upgraded.

The major problem with this, is that it's incredibly invasive and annoying, so we're currently only using it for major version updates, rather than minors, so as not to infuriate our users when we do fast releases. Clearly, that makes the system significantly less useful.

The second problem is that the message in the notifcation is hardcoded inside of Ghost, and that makes it not particularly useful. There's no way to say 'hey, this interesting thing happened and that's why you should update'. There's also no way to send a notification outside of a version change, which is quite limiting.

To make this whole system SIGNIFICANTLY more useful both to us and to our users, I want to make the following changes:

Move the "update available" notification to the about page.

As this is where the version information is currently shown, lets show the update information here. It means that users have to check the page to find out, but it does at least mean the information is always to hand in an easy to find place.

Add support for custom messages

The updates endpoint on Ghost.org is going to be updated to send back a little bit more JSON, that will look like this by default:

{
  "version": "0.5.0",
  "next_check": 1427366737,
  "messages": []
}

When we want to display a message to our users, it will look like this

{
  "version": "0.5.0",
  "next_check": 1427366737,
  "messages": [{
    "id": ed9dc38c-73e5-4d72-a741-22b11f6e151a,
    "version": "0.5.x",
    "content": "<p>Hey there! 0.6 is available, visit <a href=\"https://ghost.org/download\">Ghost.org</a> to grab your copy now<!/p>" 
  ]}
}

The intention is that Ghost will read these, and display these custom notifications in the top notification spot where update notifications used to go, allowing us to push a particular release or feature, without interfering with the general concept of 'is there an update available'. The 'top' notifications will need to be changed to be dismissible, unlike the existing version.

Note: At some point since 0.5.0, there has been a regression in the notification system, such that top notifications are no longer shown in the correct spot at the top of the screen, but appear in the normal bottom left 'toaster' location. This will need fixing.

Each custom message from Ghost.org will have 3 properties, firstly a GUID which should be stored in an array of seenNotifications in the settings table once a message is dismissed, so that the message is not shown again. Secondly, a version string which adheres to semver - this is to indicate which versions of Ghost the notification should be shown to. Finally the HTML content for the notification is provided in full, but should be sanitized via the caja tools already in the Ghost admin client, to ensure this cannot be abused.

Once we have this in place, we then have 2 different notification concepts driven on versioning - whether or not there is an update available, which is simple factual information and custom messages, which provide an opportunity to communicate important details to our users.

• [x] update LTS code base
• [ ] port changes to 1.0, https://github.com/TryGhost/Ghost/pull/9123
• [x] add UI @kevinansfield, https://github.com/TryGhost/Ghost-Admin/pull/894

[nuclearpengy]

+1 :)

[joshkerr]

+1

[crepererum]

Please be careful with the content field. Otherwise code injections to ALL running ghost installations are possible in case that the central update notifier gets compromised. That's a way higher security threat than compromised download files, because the admins have no chance to prevent this and aren't even aware of this potential attack scenario.

[ErisDS]

@crepererum This is a very good point, and not one that had escaped my attention. I think it's expected that any notification pulled from an external source should be run through the html_sanitizer to remove potentially dangerous code and I've updated the issue to say this explicitly.

[naz]

Hi @ErisDS . Is anyone in particular working on this issue or it could be taken to finish up?
Haven't contributed in a while and would love to start again from something :smiley:

[ErisDS]

Hi @Gargol no one is working on this - so it's all yours :+1: Welcome back :smiley:

[naz]

@ErisDS was looking into this issue last night and thought that it's closely related to this refactoring of notification system #5409. After reviewing the changes that are being done there, have couple related questions.

1. Does update notification on about page fall into the category of Alerts? Or maybe this this should be just completely different concept that is only used on about page (on the mockup it's just a red text that will be configurable) ?
2. What about those version specific messages? What category should those fall into?

Let me know, if I'm missing something. Maybe there is some guideline for these specific version update notifications that I've missed :smirk:

[naz]

@ErisDS ping.

[ErisDS]

Hi @Gargol, sorry for the delay. This issue was written before the frontend notification refactor was spec'd and there hasn't been much consideration for how the changes proposed here fit in with the changes being made elsewhere.

1. Does update notification on about page fall into the category of Alerts? Or maybe this this should be just completely different concept that is only used on about page (on the mockup it's just a red text that will be configurable) ?

The notification on the about page is intended to be something different to an alert. Just a message which appears on that page when there is an update available. In future it'd be cool to have an indicator in the navigation ui that this message is there (like red bubble number indicators that are common in iOS, slack, etc) - that's not expected as part of this issue but just something to keep it in mind that that is how this is being thought of - as a notification which belongs to a specific part of the Ghost interface, instead of a global notification.

1. What about those version specific messages? What category should those fall into?

They should be alerts. Alerts are the old 'top' notifications, but they are dismissible, which is what was spec'd in the issue here, so that part of the work is done already :)

[naz]

While implementing seenNotifications part, had a thought about future clean up of this information. Let's say we are 20 versions upstream and the end user will be having ~20 ids in seenNotifications row in settings table. Should we maybe think about some kind of cleanup for these records, as they should not be able to grow indefinitely?

[ErisDS]

@Gargol sorry for the ridiculously slow response here. I don't think cleanup is something that really needs to be thought in the short term, as it would take a long time to get to even 20 ids.

[ErisDS]

@kirrg001 Reopening this issue to work against, because most of what is written here is what you are working on 😁

[kirrg001]

@ErisDS

Do we want to show the update notifications in the about page for LTS as well? 🤔 Personally, I would say we add this modification only for 1.0? What do you think?

That would mean for LTS:

• we make the update notification dismissible (to reduce the pain for the users)
• the update check service sends the message, which Ghost will show (we remove the hardcoded message)
• LTS is able to show a custom message
• the update check service can control everything e.g. how often you see a notification
• so the only difference in LTS would be where to show the notification

[ErisDS]

Personally, I would say we add this modification only for 1.0?

Can you explain the reasons?

The use cases we have are:

• Not bombard people with blue-bar notifications for every available upgrade
• Give them somewhere to see what the latest version is (about page)
• Give ourselves the ability to trigger a blue bar (now also dismissible) to invite people to upgrade to 1.0 and then later to warn them when 0.11 gets towards the end of life

If we can solve these usecases for pro and non-pro users, then the implementation doesn't matter, but if we turn off top-bar notifications for new versions and don't show anything on the about page either, then we are missing information?

[kirrg001]

This was merged into LTS. I had no time so far to finish the PR for master. Simply because of other priorities. I think it's a 1-2 days work to finally get the changes merged into 1.0. And then we are able to close this issue 😁

[kirrg001]

Regarding the pull requests to master (server, admin).

So in the past Ghost fetched release notifications from the update check service with a delay of one day - otherwise too many requests were being made to the service. And the admin client pulled the cached notifications from Ghost.

With notifications 2.0, we have a differentiation between release and custom notifications.

If we put release notifications into the about page for master (see), we can't detect if a user has seen the release notification and it's also not really important. A seen notification tells the server that this notification can be removed. That's why the admin client fetches the update check url from Ghost's configuration endpoint and requests the latest release notification directly from the service, see.

Users do not often visit the about page, that's why there is no urgent reason to add a one day request delay logic. But if we want to add a little badge to show that a new release is available (somewhere over the little menu left-top), we would have to add a delay. But both cc @kevinansfield. Both is no high priority and needs confirmation first, but i still wonder how we communicate that a new release notification is available.

And any custom notification is pulled from Ghost. This can be any notification - even a custom release notification because of a security fix. It's shown as a top bar element and can be configured to be dismissible or not (i think 99% of notifications are dismissible).

The service can also provide a custom notification, which should not be displayed on top, because any parameter (top, dismissible etc.) is just a boolean we can set. But as long as we don't have a clear use case, there is no need to support this feature in the admin. That means we simply don't support none-top custom notifications for now. If we want to support them, we can either show them in the about page or in a separate notification menu section or...or...

[kevinansfield]

But if we want to add a little badge to show that a new release is available (somewhere over the little menu left-top), we would have to add a delay.

This isn't particularly hard to add in the client, we can store the last version and checked date in local storage with the auth data. We then have the option of using the cached value for a badge and forcing a check on the about screen or using the cached value everywhere.

[kirrg001]

This isn't particularly hard to add in the client, we can store the last version and checked date in local storage with the auth data. We then have the option of using the cached value for a badge and forcing a check on the about screen or using the cached value everywhere.

Cool, thanks for feedback. But not for the first version. The first version will simply show if a new release is available or if your blog is up-to-date (on the about page).

[kirrg001]

See https://github.com/TryGhost/Ghost/pull/9123#issuecomment-347524933.