Required API version for Apps

[sebgie]

To ensure that an app is compatible with the installed Ghost version apps should provide the expected API version. App installation then checks if the required api version matches the available api version and provides feedback if the installed version of Ghost is not compatible.

I would propose that available and required api version are stored in package.json:

App package.json:

{
    "ghost": {
        ...
        "required-api-version": "0.1.0",
        ...
    }
}

Ghost package.json:

{
    "name"        : "ghost",
    "version"     : "0.4.1",
    "api-version" : "0.1.0",
    ...
}

After introducing a version for the API we need to make sure that we do not introduce breaking changes to the API and keep legacy/deprecated versions of changed interfaces for some time.

[javorszky]

So if I'm reading this right:
app.required.apiversion > ghost.apiversion = error
app.required.apiversion < ghost.apiversion = works, but deprecated
app.required.apiversion = ghost.apiversion = awsm
?

[ErisDS]

What does API version represent? The version of the JSON API, or the whole Apps GDK as represented by the proxy object?

[sebgie]

@javorszky good point I had versioning like semver in mind:

Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

Example:

app.required.apiversion.major > ghost.apiversion.major = error -> update Ghost
app.required.apiversion.minor > ghost.apiversion.minor = error -> update Ghost
app.required.apiversion.major = ghost.apiversion.major = works, but some functions are deprecated and removed in next major version
app.required.apiversion.minor < ghost.apiversion.minor = works, but some functions are deprecated and removed in next major version

@ErisDS I think that we could use one version number for the whole Apps GDK. The biggest problem I see is that all apps would need updating if we introduce a breaking change no matter if the app uses the changed API or not. On the other hand, I really don't want to end up with 10+ different version numbers for all the APIs available?

While thinking about it, maybe we should also introduce version numbers for themes? -> new issue?

[halfdan]

@sebgie I don't think it is necessary for themes. The theme API should not introduce breaking changes and even if a helper breaks BC we can simply show an error message in the console and have the rest of the theme work.

[ErisDS]

Re themes:

Might a good idea to use the package.json file to determine which version of Ghost the theme was built for? Not sure if we need to implement any checking around it just yet as there isn't much of a UI, but one for the future I think.

---

In terms of the GDK, does it make sense to have a separate version number, or should apps also just define the version of Ghost with which they work.. or rather which version of the Ghost-App module, which is the link between the two things & required as a dependency in package.json anyway?

This means, I think, we need to create a link (which we ought to have any way) between the Ghost-App module, and which version of Ghost it should be used with, or vice versa.

Does it make more sense to say Ghost 0.5.0 supports Ghost-App 0.1., or that Ghost-App 0.1.0 works with Ghost 0.5.?

[javorszky]

Works with is more user friendly than supports I think.

[sebgie]

If every app needs to require Ghost-app as dependency I think that linking between API version and Ghost version could be done that way. In fact the Ghost-app version is then equivalent to what I introduced as required-api-version.

We would have to check if the required Ghost-App version is supported/works with the installed version of Ghost.

Examples (assuming that Ghost 0.5 works with Ghost-App 0.1.0 and Ghost 0.6 works with Ghost-App 0.3.0):

• Ghost 0.5.0 and Ghost-App 0.1.0 -> Works
• Ghost 0.6.0 and Ghost-App 0.1.0 -> Works, but some functions are deprecated
• Ghost 0.6.0 and Ghost-App 0.3.0 -> Works
• Ghost 0.5.0 and Ghost-App 0.2.0 -> Error, Update Ghost

[ErisDS]

Temporarily closing all of the app specific issues (tagged with later). Will review & reopen those that are still relevant when we kick off that project, which should be shortly after Zelda lands.