Skip to content

UPGRADE.md

Latest commit

 

History

History
87 lines (82 loc) · 5.69 KB

UPGRADE.md

File metadata and controls

87 lines (82 loc) · 5.69 KB

UPGRADING

The releases of Shopsys Framework adhere to the Backward Compatibility Promise to make the upgrades to new versions easier and help long-term maintainability.

Recommended way of upgrading

Since there are 3 possible scenarios how you can use the Shopsys Framework, instructions are divided into these scenarios.

You use our packages only

Follow the instructions in relevant sections, eg. shopsys/coding-standards or shopsys/http-smoke-testing.

You are using the monorepo

Follow the instructions in the monorepo upgrade guide.

You are developing a project based on the project-base repository

  • upgrade only your composer dependencies and follow the instructions in a guide below
  • upgrade locally first - after you fix all issues caused by the upgrade, commit your changes, test your application and then continue with a deployment onto your server
  • upgrade one version at a time:
    • start with a working application
    • upgrade to the next version
    • fix all the issues you encounter
    • repeat
  • check the instructions in all sections, any of them could be relevant for you
  • typical upgrade sequence should be:
    • run docker-compose down to turn off your containers
    • (MacOS, Windows only) run docker-sync clean so your volumes will be stopped and removed
    • follow upgrade notes in the Infrastructure section (related with docker-compose.yml, Dockerfile, docker containers, nginx.conf, php.ini, etc.)
    • (MacOS, Windows only) run docker-sync start to create volumes
    • run docker-compose build --no-cache --pull to build your images without cache and with latest version
    • run docker-compose up -d --force-recreate --remove-orphans to start the application again
    • update the shopsys/* dependencies in composer.json to version you are upgrading to
      • eg. "shopsys/framework": "v7.0.0"
    • follow upgrade notes in the Composer dependencies section (related with composer.json)
    • run composer update shopsys/* --with-dependencies
    • update the @shopsys/framework package in your package.json (in "dependencies" section) to the version you are upgrading to
      • eg. "@shopsys/framework": "9.0.4",
    • run npm install to update the NPM dependencies
    • follow all upgrade notes you have not done yet
    • run php phing clean
    • run php phing db-migrations to run the database migrations
    • test your app locally
    • commit your changes
    • run composer update to update the rest of your dependencies, test the app again and commit composer.lock
  • if any of the database migrations does not suit you, there is an option to skip it, see our Database Migrations docs
  • even we care a lot about these instructions, it is possible we miss something. In case something doesn't work after the upgrade, you'll find more information in the CHANGELOG

Upgrade guides