CLI support for Ghost 2.0 #759

kirrg001 · 2018-07-20T22:29:23Z

We will release a new minor CLI version before we release Ghost 2.0. This new CLI version will add support to upgrade your blog to Ghost 2.0. Furthermore the new CLI version will add support to stay on Ghost 1.0.

Changes explained

Install/Update a Ghost 2.0 blog

If you execute ghost update and your are on 1.0, you will update to the next major. If you are on the next major (Ghost 2.0) and you execute ghost update you will update to the next Ghost 2.x release.

If you execute ghost install you will install a Ghost 2.0 blog.

Install/Update a Ghost 1.0 blog

The CLI will add a new flag --v1. This flag will tell the CLI to either install or update a Ghost 1.0 blog (ghost install --v1 or ghost update --v1).

e.g. People who are still on LTS need an option to install a Ghost 1.0, because we disallow the jump from LTS to 2.0. We will only support the latest (2.0) and the previous (1.0) version. This is a new general concept we came up with. The same rule applies to GScan.

e.g. If we release a new 1.0 release after the Ghost 2.0 release, you can upgrade your blog to the latest 1.0 release with ghost update --v1.

Guide to upgrade to Ghost 2.0

The CLI will add a proper support for the migration to Ghost 2.0

print link to a new migration guide, which explains how the migration works
scan your theme with GScan
output the report from GScan
print a link to the new demo draft post we will ship next week (a post about how the new editor König works)
the ability to continue/abort the major migration
if the user continues
- the CLI will download/install Ghost 2.0
- Ghost 2.0 will use the same blog config
- CLI will stop the 1.0 blog
- CLI will start the 2.0 blog
- Ghost 2.0 will bring the blog automatically into maintenance mode
- Ghost 2.0 will then run the migration scripts
- if successful, blog is out of maintenance mode
  - we use a net server communication (which is optional and needs to be configured from the outer unit)
- if an error occurs during migrations, knex-migrator will auto rollback, the CLI must react and symlink the previous 1.0 version and start the blog
  - we have to send a socket + child event to receive the proper error message
if the user aborts
- the user stays on Ghost 1.0, nothing happens

Ghost 2.0 will tag this new CLI release as minimum cli engine version in the package.json. This will avoid that people with an older CLI version can update to Ghost 2.0. We want that they can enjoy our guidance to jump to the next major version.

Knex-Migrator

Knex-Migrator will be the main instrument to jump from Ghost 1.0 to Ghost 2.0.
We will add migration scripts into Ghost 2.0, which will get executed when the Ghost 2.0 blog starts.

We will move the execution of Knex-Migrator from the CLI to Ghost core. The main reason is that we currently have three components which need to execute knex-migrator: the CLI, local development and Ghost(Pro). We think it makes sense to put it back into Ghost core. Therefor we will add a new condition into the CLI to only execute knex-migrator if the blog is on 1.0. We have to ensure that knex-migrator is still called for Ghost 1.0 blogs.

`ghost update` should be smoother

This issue is tracked here.

In discussion

We might force the user to upgrade to the latest Ghost 1.0 version before they can jump to Ghost 2.0. The main reason is that we might remove the 1.0 migration scripts in 2.0. But this is still in discussion.

I thought it makes sense to raise this is as early as possible. If you have any questions or concerns, just leave a comment.

The text was updated successfully, but these errors were encountered:

vikaspotluri123 · 2018-07-20T22:30:20Z

Let me know if there's anything you would like for me to do! 😄

kirrg001 · 2018-07-20T22:36:17Z

@vikaspotluri123 Thanks so much! 🙃

I will start with the implementation on Wednesday next week. First of all, if you want you could read the issue and check if we have forgotten anything e.g. problems we can run into, edge cases.

Furthermore, you could let me know till Wednesday which task you are interested in and then we can talk about it :)

vikaspotluri123 · 2018-07-21T01:16:11Z

I've been thinking about the --v1 flag - imo it's kind of specific - When ghost n+1 releases, we will need to add the --v{n} flag. Since there's a lot of work required to release a semver major relase, this might be something to think about afterwards - maybe a --version {n} flag 🤔

Other than that I can't think of anything, but I'll definitely post if I do!

kirrg001 · 2018-07-21T12:30:18Z

When we release Ghost 3.0, we only have to change --v1 to --v2. Could be one global configuration flag.

I agree the notation can be discussed. We already have a --version parameter in the CLI to install specific Ghost versions, but we still need a way to define e.g. ghost update --v1.

vikaspotluri123 · 2018-07-21T14:06:57Z

That's right!

When 2.0 is released would 1.0 be considered LTS?
When 3.0 is released will it still be ~~possible~~ allowable to install 1.0?

kirrg001 · 2018-07-21T15:52:33Z

When 3.0 is released will it still be possible allowable to install 1.0?

Hmm i don't think so - not with the latest CLI version.

vikaspotluri123 · 2018-07-21T16:51:55Z

So based on that, could we just use an --lts flag instead? 🤔

acburdine · 2018-07-21T19:34:43Z

So based on that, could we just use an --lts flag instead? 🤔

+1 to that approach.

My thought is we could potentially make use of npm's dist-tags feature. In doing so, we could publish Ghost 2.0 prereleases (if we want to do that) to npm's next tag, and people could potentially install it using ghost install --next or ghost update --next. We could add a disclaimer or something in Ghost-CLI in the meantime so that when Ghost 2.0 does get released, people would see something like this:

$ ghost update
Ghost 2.0 has been released! Please note that upgrading to Ghost 2.0 will
put your blog in "maintenance mode" while migrations are being run. 
<insert docs link here>
Do you wish to upgrade to 2.0? (y/n)

Running ghost update --next at this point would skip the prompt. ghost install would install 2.0, and then you could run ghost install --lts or ghost update --lts, which could use npm's lts dist tag, meaning that LTS releases would be more distinct from mainline 2.0 releases.

Hopefully that makes sense 😅 I think it's an approach that will be more flexible and also be a bit more maintainable in the future.

refs TryGhost#9742, refs TryGhost/Ghost-CLI#759 - required a reordering of Ghost's bootstrap file, because: - we have to ensure that no database queries are executed within Ghost during the migrations - make 3 sections: check if db needs initialisation, bootstrap Ghost with minimal components (db/models, express apps, load settings+theme) - create a new `migrator` utility, which tells you which state your db is in and offers an API to execute knex-migrator based on this state - ensure we still detect an incompatible db: you connect your 2.0 blog with a 0.11 database - enable maintenance mode if migrations are missing - if the migration have failed, knex-migrator roll auto rollback - you can automatically switch to 1.0 again - added socket communication for the CLI

refs #9742, refs TryGhost/Ghost-CLI#759 - required a reordering of Ghost's bootstrap file, because: - we have to ensure that no database queries are executed within Ghost during the migrations - make 3 sections: check if db needs initialisation, bootstrap Ghost with minimal components (db/models, express apps, load settings+theme) - create a new `migrator` utility, which tells you which state your db is in and offers an API to execute knex-migrator based on this state - ensure we still detect an incompatible db: you connect your 2.0 blog with a 0.11 database - enable maintenance mode if migrations are missing - if the migration have failed, knex-migrator roll auto rollback - you can automatically switch to 1.0 again - added socket communication for the CLI

kirrg001 · 2018-07-22T14:45:45Z

So based on that, could we just use an --lts flag instead?

Interesting suggestion. Will discuss && confirm asap.

In doing so, we could publish Ghost 2.0 prereleases

I don't think it will happen this time. Not planned.

make use of npm's dist-tags feature

This is in general a nice idea. I just wonder if you can use the lts tag for multiple Ghost versions e.g. ghost install --lts --version 1.20

refs TryGhost#759 - return a proper GhostError when migration fails - detect if knex-migrator can't find versions to rollback (resolve in this case)

…e on latest v1 refs TryGhost#759

…sion (TryGhost#771) refs TryGhost#759 - executed new task if you are migrating from v1 to v2 - do not execute the new task if you are migrating from v1 to v1 - do not execute the new task if you are already on v2 - this task will: - scan your theme with GScan 2.0 - load the demo post from your database - show a nice UI and prompts - added unit tests

refs TryGhost#759 - `semver.satisfies(version, '^2.0.0')` doesn't work with release candidates - switch to compare the major version with `semver.major`

…t folder refs TryGhost#759 - if your active theme is "casper", we have to validate the casper theme from the v2 folder - otherwise we will validate casper from Ghost v1 with GScan v2

…ing a zip refs TryGhost#759 - helpful for testing - otherwise we allow a direct jump from e.g. 1.20 to 2.0 and this will crash - it will crash because Ghost v2 can't execute v1 migration scripts, because the context/code has changed

refs #759 - adds --v1 flag to install and update commands - add arg to resolveVersion util that limits versions to 1.x releases

refs #759 - extended version resolver - detected major version jumps - optimised code around the force flag - added unit tests

refs #759 - ask user if we wants to bring back previous version if - GhostError was thrown (migration failed) - if the user has not executed `ghost update --rollback` - show error to user so he knows why the update failed

refs #759 - return a proper GhostError when migration fails - detect if knex-migrator can't find versions to rollback (resolve in this case)

refs #759

refs #759 - executed new task if you are migrating from v1 to v2 - do not execute the new task if you are migrating from v1 to v1 - do not execute the new task if you are already on v2 - this task will: - scan your theme with GScan 2.0 - load the demo post from your database - show a nice UI and prompts - added unit tests

refs #759 - `semver.satisfies(version, '^2.0.0')` doesn't work with release candidates - switch to compare the major version with `semver.major`

refs #759 - if your active theme is "casper", we have to validate the casper theme from the v2 folder - otherwise we will validate casper from Ghost v1 with GScan v2

refs #759 - helpful for testing - otherwise we allow a direct jump from e.g. 1.20 to 2.0 and this will crash - it will crash because Ghost v2 can't execute v1 migration scripts, because the context/code has changed

refs #759 - We have moved the execution of knex-migrator into Ghost 2.0.0 - This commit will ensure we skip the db migration when you: - migrate from ^1 to ^2 - you update from ^2 to ^2 - when you install ^2 - Added net socket server for Ghost 2.0 (alternative to simple port polling) - way better error handling between Ghost and the CLI - Ghost 2.0 executes knex-migrator - it will turn maintenance on if migrations need to be executed - the handling of receiving success or failure state requires a better communication between the CLI and Ghost, because the blog stays in maintenance mode and runs the migrations in background - Ghost will tell the CLI when it's ready by using an extension: write a socket url into the config and send the success/failure state - this is much better than using the http socket to communicate, because - A) port polling connects to the http port, it's impossible to send simple messages over this transport layer - B) the code is much simpler, CLI opens a socket port and Ghost pushes a notification if the notification is available - C) we receive any error from Ghost - even if the http server wasn't started yet - we don't communicate with Ghost, Ghost communicates with the CLI - port polling for v1 blogs is untouched, still works as expected - coverage has decreased a very little 0,2% - will try to add more tests when we merge the 1.9 branch into master

refs #759 - adds --v1 flag to install and update commands - add arg to resolveVersion util that limits versions to 1.x releases

refs #759 - extended version resolver - detected major version jumps - optimised code around the force flag - added unit tests

refs #759 - ask user if we wants to bring back previous version if - GhostError was thrown (migration failed) - if the user has not executed `ghost update --rollback` - show error to user so he knows why the update failed

refs #759 - return a proper GhostError when migration fails - detect if knex-migrator can't find versions to rollback (resolve in this case)

refs #759

refs #759 - executed new task if you are migrating from v1 to v2 - do not execute the new task if you are migrating from v1 to v1 - do not execute the new task if you are already on v2 - this task will: - scan your theme with GScan 2.0 - load the demo post from your database - show a nice UI and prompts - added unit tests

refs #759 - `semver.satisfies(version, '^2.0.0')` doesn't work with release candidates - switch to compare the major version with `semver.major`

refs #759 - if your active theme is "casper", we have to validate the casper theme from the v2 folder - otherwise we will validate casper from Ghost v1 with GScan v2

refs #759 - helpful for testing - otherwise we allow a direct jump from e.g. 1.20 to 2.0 and this will crash - it will crash because Ghost v2 can't execute v1 migration scripts, because the context/code has changed

kirrg001 · 2018-08-16T09:48:53Z

1.9 was released.

refs #9742, refs TryGhost/Ghost-CLI#759 - required a reordering of Ghost's bootstrap file, because: - we have to ensure that no database queries are executed within Ghost during the migrations - make 3 sections: check if db needs initialisation, bootstrap Ghost with minimal components (db/models, express apps, load settings+theme) - create a new `migrator` utility, which tells you which state your db is in and offers an API to execute knex-migrator based on this state - ensure we still detect an incompatible db: you connect your 2.0 blog with a 0.11 database - enable maintenance mode if migrations are missing - if the migration have failed, knex-migrator roll auto rollback - you can automatically switch to 1.0 again - added socket communication for the CLI

refs TryGhost/Ghost-CLI#759 - to be able to install Ghost 2.0, you have to be on the version Ghost CLI 1.9.0 - 1.9.0 will add a proper support for migrating to a new major version

refs TryGhost/Ghost-CLI#759 - Ghost will announce the server start or failure in each case - therefor you have to configure a bootstrap socket host and port

kirrg001 self-assigned this Jul 20, 2018

kirrg001 assigned vikaspotluri123 Jul 20, 2018

acburdine pushed a commit to acburdine/Ghost-CLI that referenced this issue Aug 16, 2018

fix(v2): Fixed ghost update --force to jump to next major if you ar…

c674732

…e on latest v1 refs TryGhost#759

acburdine pushed a commit to acburdine/Ghost-CLI that referenced this issue Aug 16, 2018

fix(v2): changed major version comparison

c4b9e07

refs TryGhost#759 - `semver.satisfies(version, '^2.0.0')` doesn't work with release candidates - switch to compare the major version with `semver.major`

acburdine added a commit that referenced this issue Aug 16, 2018

feat(flag): add --v1 flag to install and update

1e9c94c

refs #759 - adds --v1 flag to install and update commands - add arg to resolveVersion util that limits versions to 1.x releases

acburdine pushed a commit that referenced this issue Aug 16, 2018

feat(v2): avoid direct upgrade to v2 (#770)

3d486cb

refs #759 - extended version resolver - detected major version jumps - optimised code around the force flag - added unit tests

acburdine pushed a commit that referenced this issue Aug 16, 2018

fix(migrate): optimise error handling in migrator task

eae5e97

refs #759 - return a proper GhostError when migration fails - detect if knex-migrator can't find versions to rollback (resolve in this case)

acburdine pushed a commit that referenced this issue Aug 16, 2018

fix(v2): ensure ghost update --force correctly jumps to v2

27d0473

refs #759

acburdine pushed a commit that referenced this issue Aug 16, 2018

fix(v2): changed major version comparison

8e694f4

refs #759 - `semver.satisfies(version, '^2.0.0')` doesn't work with release candidates - switch to compare the major version with `semver.major`

acburdine added a commit that referenced this issue Aug 16, 2018

feat(flag): add --v1 flag to install and update

eb315c3

refs #759 - adds --v1 flag to install and update commands - add arg to resolveVersion util that limits versions to 1.x releases

acburdine pushed a commit that referenced this issue Aug 16, 2018

feat(v2): avoid direct upgrade to v2 (#770)

702e953

refs #759 - extended version resolver - detected major version jumps - optimised code around the force flag - added unit tests

acburdine pushed a commit that referenced this issue Aug 16, 2018

fix(migrate): optimise error handling in migrator task

be2c923

refs #759 - return a proper GhostError when migration fails - detect if knex-migrator can't find versions to rollback (resolve in this case)

acburdine pushed a commit that referenced this issue Aug 16, 2018

fix(v2): ensure ghost update --force correctly jumps to v2

8093274

refs #759

acburdine pushed a commit that referenced this issue Aug 16, 2018

fix(v2): changed major version comparison

d243bed

refs #759 - `semver.satisfies(version, '^2.0.0')` doesn't work with release candidates - switch to compare the major version with `semver.major`

kirrg001 closed this as completed Aug 16, 2018

kirrg001 added a commit to TryGhost/Ghost that referenced this issue Aug 16, 2018

Added bootstrap socket extension

0e52179

refs TryGhost/Ghost-CLI#759 - Ghost will announce the server start or failure in each case - therefor you have to configure a bootstrap socket host and port

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI support for Ghost 2.0 #759

CLI support for Ghost 2.0 #759

kirrg001 commented Jul 20, 2018 •

edited

Loading

vikaspotluri123 commented Jul 20, 2018

kirrg001 commented Jul 20, 2018 •

edited

Loading

vikaspotluri123 commented Jul 21, 2018

kirrg001 commented Jul 21, 2018

vikaspotluri123 commented Jul 21, 2018

kirrg001 commented Jul 21, 2018 •

edited

Loading

vikaspotluri123 commented Jul 21, 2018

acburdine commented Jul 21, 2018 •

edited

Loading

kirrg001 commented Jul 22, 2018 •

edited

Loading

kirrg001 commented Aug 16, 2018

CLI support for Ghost 2.0 #759

CLI support for Ghost 2.0 #759

Comments

kirrg001 commented Jul 20, 2018 • edited Loading

Changes explained

Install/Update a Ghost 2.0 blog

Install/Update a Ghost 1.0 blog

Guide to upgrade to Ghost 2.0

Knex-Migrator

ghost update should be smoother

In discussion

vikaspotluri123 commented Jul 20, 2018

kirrg001 commented Jul 20, 2018 • edited Loading

vikaspotluri123 commented Jul 21, 2018

kirrg001 commented Jul 21, 2018

vikaspotluri123 commented Jul 21, 2018

kirrg001 commented Jul 21, 2018 • edited Loading

vikaspotluri123 commented Jul 21, 2018

acburdine commented Jul 21, 2018 • edited Loading

kirrg001 commented Jul 22, 2018 • edited Loading

kirrg001 commented Aug 16, 2018

kirrg001 commented Jul 20, 2018 •

edited

Loading

`ghost update` should be smoother

kirrg001 commented Jul 20, 2018 •

edited

Loading

kirrg001 commented Jul 21, 2018 •

edited

Loading

acburdine commented Jul 21, 2018 •

edited

Loading

kirrg001 commented Jul 22, 2018 •

edited

Loading