Ghost 1.0

[vickychijwani]

Ghost 1.0 is releasing this month, which means big breaking changes are imminent. I'm tracking all of the potential changes on this wiki page: https://github.com/vickychijwani/quill/wiki/Changes-for-Ghost-1.0. Specific todos will be added to this issue as they are formulated.

All work for this issue is happening in the wip-ghost-1.0 branch.

Mandatory changes

• GhostAuth: this is going to be the default auth mechanism starting from 1.0. Since there doesn't seem to be an official way to add new OAuth clients atm, we'll have to still masquerade as Ghost Admin (like we do now). (UPDATE: Ghost Auth is disabled in Ghost now, apparently it will not ship in 1.0. See Remove/Disable Ghost authentication for now TryGhost/Ghost#8342.)
  • Re-authenticate on token expiry
• Password auth: the old auth mechanism will also be supported by Ghost, so we must have compatibility with password auth as well.
  • Re-authenticate on token expiry
• Configuration endpoint schema changed: the new schema for the (now public) /configuration/ endpoint uses a typed-JSON dictionary, where the values can be bools, strings, or even objects.
• Token expiry increased: access token expires after 30 days and refresh token after 180 days; refresh token expiry is delayed each time the access token is refreshed, so we should just get rid of hasRefreshTokenExpired and, indeed, hasAccessTokenExpired since the expiry times are very long. (note: this change is also included in Ghost 0.11.5 LTS)
• Data model changes:
  • Numeric sequential IDs to String UUIDs: Remove all instances where we're relying on the numeric nature of IDs (e.g., Comparator for sorting posts).
  • markdown field removed, superseded by mobiledoc field: - see comment below and these issues
  • post.image field renamed to feature_image
  • user.image field renamed to profile_image
  • Database migration: probably just drop the database if it's at v3? Since we won't support Ghost 0.x.
• File storage permanently enabled: It looks like file storage will always be available in Ghost 1.x, so the fileStorage: true/false config option is going away.
• Showdown replaced with markdown-it: Changes enumerated here.
• Collision detection for edits? - are there any changes requires for this? (ref: Use updated_at to prevent overwriting new data with old data. TryGhost/Ghost#5599 and the 2 associated PRs)

Bugs

• Memory leak on login screen

Optional changes

• Notify the user if they're using Ghost 0.x and we expect 1.x: ask them to upgrade their blog, or to download the old app version for Ghost 0.x from the Play Store (as a separate app, "Quill for Ghost v0", which will not receive further updates)
• Upload APK for Ghost 0.x with different app id
• Persistence overhaul: Since a significant database change is needed for this anyway, this would be a good time to rework the Realm storage architecture in preparation for Support multiple blogs #148 by storing each blog's data in a separate Realm file.
  • Preserve the data Realm in the case where, e.g., credentials expire
  • Delete the data Realm when a blog is removed (i.e., logged out)
• Drop API 15 support - Drop support for Ice Cream Sandwich? (It's at 1.4% now) #101
• Add a link on the login screen to get help for login issues - maybe also link to Ghost setup docs at https://docs.ghost.org/
• Analytics: Especially successful and failed user logins + users who were rejected because they are not on Ghost 1.0
• Crashlytics logging: Especially during login

Misc stuff

• Test schema migration
• Tablet layouts for login
• Test token / auth code expiry
• Update Play Store listing to reflect these changes and maybe drop the warnings about stability

[kirrg001]

Hey @vickychijwani 👋

This is Kate from Ghost. It's very exciting for us to see how much you care about the Ghost 1.0 changes. Very impressive! Our goal is to release the beta on Thursday. It's finally happening 😝

I wanted to share some details about our mobiledoc editor.

The initial plan was to ship the new mobiledoc editor with 1.0, but the complexity of edge cases and the wish to finally release 1.0 forced us to revert the editor for now. Instead we have added SimpleMDE, a new and better markdown editor, which fills this gap for now.

But the idea is still to ship the mobiledoc editor as soon as possible. And that's why we decided to keep the mobiledoc post field and mobiledoc format, to be able to switch to mobiledoc easily.

That means:

• the markdown field in the post model was removed
• the Ghost API expects mobildoc format with a single markdown card (which contains markdown content)

Format in Ghost 0.11.x

{ 
  "markdown": "## headline"
}

Format in Ghost 1.0

{
  "version":"0.3.1",
  "markups":[],
  "atoms":[],
  "cards":[
     ["card-markdown", {
         "cardName": "card-markdown", 
         "markdown": "# headline"
      }]
    ],
 "sections":[[10,0]]   // a static value for now
}

External clients (like quill) are required to send this format for 1.0.

We thought about keeping the ability to send/receive markdown to/from the Ghost API, which then get's transformed into mobiledoc format, which would be easier for external clients like quill. But we would like to wait how complicated this requirement is and that the reason keeping the mobiledoc format is understood from our external clients.

Thanks so much for quill!
If you have any questions, come say hello on slack!

[vickychijwani]

Hi @kirrg001 🙂

I'm looking forward to the 1.0 beta!

Your comment clarifies the changes I would need to make, and having visibility into the Ghost team's thought process provides useful context. I'll need to dig deeper into the mobiledoc format to understand what all those fields mean, but this is a great starting point. Thank you!

I'll reach out via Slack for any questions.