This page explains how to update between minor or patch versions= of eZ Platform.
If you are looking for information on how to upgrade to eZ Platform from= eZ Publish (4.x or 5.x), take look at the Upgrade doc.
This instruction reflects a proposed git-based workflow for handling upd= ates; feedback on how this works in practice and input on how to further im= prove/simplify it is welcome.
In the instructions below, replace <version> with the=
version of eZ Platform you are updating to (for example: v1.2.0).
If you are testing a release candidate, use the latest rc tag (for example: v1.2.1-rc1).
Existing projects can easily be updated using Composer. From the project= 's root, create a new branch from the project's master, or from the branch = you're upgrading on:
git checkout -b <branch_name>=20
If it's not there, add ezsystems/ezplatform as an upstream =
remote:
git remote add ezplatform http://github.com/ezsystems/ezplatform.g= it=20
Then pull the tag into your branch:
git pull ezplatform <version>=20
You will get conflicts, and it is perfectly normal. The most common ones=
will be on composer.json and composer.lock.=
The latter can be ignored, as it will be regenerated when we execute co=
mposer update later. The easiest is to checkout the version from the tag, a=
nd add it to the changes:
If you get a lot of conflicts (on the doc folder for instance), and eZ Platform was installed from the share.e=
z.no tarball, it might be because of incomplete history. You will have =
to run git fetch ezplatform --unshallow to load the =
full history, and run the merge again.
git checkout --theirs composer.lock && git add composer.lo= ck=20
You may also run git remove composer.lock if you do no=
t keep a copy of it in the branch.
Conflicts in composer.json need to be fixed manually. =
If you're not familiar with the diff output, you may checkout the tag's ver=
sion, and inspect the changes. It should be readable for most:
git checkout --theirs composer.json && git diff composer.j= son=20
You should see what was changed, as compared to your own version, in the=
diff output. The ezplatform update changes the requirements for all of the=
ezsystems/ packages. Those changes should be left untouc=
hed. All of the other changes will be removals of what you added for your o=
wn project. Use git checkout -p to selectively cancel tho=
se changes:
git checkout -p composer.json=20
Answer no (do not discard) to the requirement cha=
nges of ezsystems dependencies. Answer yes&n=
bsp;(discard) to removals of your changes.
Once you are done, inspect the file, either using an editor or by runnin=
g git diff composer.json. You may also test the file's sanity =
with composer validate, and test the dependencies by runn=
ing composer update --dry-run. (will output what it would=
do to dependencies, without applying the changes.
Once finished, run git add composer.json.
Depending on the local changes you have done, you may get other conflict= s: configuration files, kernel...
There shouldn't be many, and you should be able to figure out which valu= e is the right one for all of them:
git add conflicting-file to add the changes<=
/li>
At this point, you should have a composer.json file with the correct req=
uirements. Run composer update to update the dependencies=
.
composer update --with-dependencies ezsystems/ezpublish-kernel ezsy= stems/platform-ui-bundle ezsystems/behatbundle=20
In order to restrict the possibility of unforeseen updates of 3rd party =
packages, we recommend by default that composer update is rest=
ricted to the list of packages we have tested the update for. You may remov=
e this restriction, but be aware that you might get a package combination w=
e have not tested.
On PHP conflict
Because from release 16.02 onwards eZ Platform is compatible only with P= HP 5.5 and higher, the update command above will fail if you use an older P= HP version. Please update PHP to proceed.
The 16.02 release required an update to the database. Import =
vendor/ezsystems/ezpublish-kernel/data/update/mysql/dbupdate-6.1.0-to-6.2.0=
.sql into your database:
mysql -u<username> -p<password> <database_name> &= lt; vendor/ezsystems/ezpublish-kernel/data/update/mysql/dbupdate-6.1.0-to-6= .2.0.sql=20
The web assets must be dumped again for the prod environment:
php app/console assetic:dump --env=3Dprod web=20
Once all the conflicts have been resolved, and composer.lock updated, the merge can be committed. Note that you may or may not ke=
ep , and merge your new update branch:composer.lock, depending on your version management wo=
rkflow. If you do not wish to keep it, run git reset HEAD <fi=
le> to remove it from the changes. Run git commit=
, and adapt the message if necessary. You can now test the project, =
run integration tests... once the upgrade has been approved, go back to
git checkout master git merge <branch_name>=20