Update docs

README.md

@@ -12,19 +12,16 @@ You can think of it as the grandson of the legacy [ezxmlinstaller](https://githu
 
 * PHP 5.4 or later.
 
-* eZ Publish Enterprise 5.4 or Community 2014.11 or later.
-
-    It is possible to use the bundle with Enterprise 5.3/Community 2014.3, but there is a known bug with those versions:
-    https://github.com/kaliop-uk/ezmigrationbundle/issues/53
+* eZPublish Enterprise 5.3 or Community 2014.3 or later.
 
 
 ## Installation
 
-In either `require` or `require-dev` at the end of the bundle list add:
+In either `require` or `require-dev` at the end of the bundle list in the composer.json file add:
 
     "kaliop/ezmigrationbundle": "^2.0"
 
-Save composer.json and run
+Save it and run
 
     composer update --dev kaliop/ezmigrationbundle
 
@@ -69,7 +66,7 @@ Please read the [dedicated documentation page](doc/Upgrading/1.x_to_2.0.md)
 
 ## Getting started
 
-All commands accept the standard Symfony/eZ publish 5 options, although some of them might not have any effect on the
+All commands accept the standard Symfony/eZPublish 5 options, although some of them might not have any effect on the
 command's execution.
 
 ### Generating a new, empty migration definition file
@@ -84,15 +81,15 @@ The above command will place a new yml skeleton file in the `MigrationVersion` d
 
 If the directory does not exists then the command will create it for you, as long as the bundle does exist and is registered.
 If the command is successful it will create a new yml file named with the following pattern: `YYYYMMDDHHMMSS_placeholder.yml`.
-You are encouraged to rename the file and change the `place_holder` part to something more meaningful, but please keep
+You are encouraged to rename the file and change the `placeholder` part to something more meaningful, but please keep
 the timestamp part and underscore, as well as the extension
 
 (the contents of the skeleton Yaml file are stored as twig template)
 
 ### Listing all migrations and their status
 
 To see all the migrations definitions available in the system and whether they have been applied or not simply run the
-status command in your eZ Publish 5 root directory:
+status command in your eZPublish 5 root directory:
 
     php ezpublish/console kaliop:migration:status
 
@@ -102,7 +99,7 @@ In case you need to use a different name for that table, you can change the Symf
 
 ### Applying migrations
 
-To apply all available migrations run the migrate command in your eZ Publish 5 root directory:
+To apply all available migrations run the migrate command in your eZPublish 5 root directory:
 
      php ezpublish/console kaliop:migration:migrate
 
@@ -186,6 +183,33 @@ The easiest way to re-execute a migration in 'failed' status, is to remove it fr
 After removing the information about the migration form the migrations table, running the `migrate` command will execute it again.
 
 
+## Usage of transactions / rolling back changes
+
+By default the bundle runs each migration in a database transaction.
+This means that if a step fails, all of the previous steps get rolled back, and the database is left at its previous state.
+This is a safety feature built in by design; if you prefer the migration steps to be executed in separate transactions
+the easiest way is to create a separate migration file for each step.
+
+Note also that by default the `migrate` command stops on the 1st failed migration, but it can be executed with a flag
+to allow it to continue and execute all available migrations even in case of failures.
+
+As for rolling back changes: given the nature of the eZPublish API, rolling back changes to Content is not an easy feat.
+As such, the bundle does not provide built-in support for rolling back the database to the version it had before
+applying a given migration. We recommend always taking a database snapshot before applying migrations, and use it in
+case you need to roll back your changes. Another approach consists in writing a separate migration to undo the changes. 
+
+
+## Known Issues
+
+* if you get fatal errors when running a migration stating that a node or object has not been found, it is most likely
+    related to how the dual-kernel works in eZPublish, and the fact that the legacy and Symfony kernels use a separate
+    connection to the database. Since the migration bundle by default wraps all database changes for a migration in a
+    database transaction, when the Slots are fired which allow the legacy kernel to clear its caches, the legacy kernel
+    can not see the database changes applied by the Symfony kernel, and, depending on the specific Slot in use, might
+    fail with a fatal error.
+    The simplest workaround is to disable usage of transactions by passing the `-u` flag to the `migrate` command.
+
+
 ## Extending the bundle
 
 ### Supporting custom migrations
@@ -203,7 +227,6 @@ and give it an appropriate tag (the class implementing service should of course
 To find out the names of the tags that you need to implement, as well as for all the other services which you can
 override, take a look at the [services.yml file](Resources/config/services.yml).
 
-
 ### Running tests
 
 The bundle uses both PHPUnit and Behat to run functional tests.

WHATSNEW.md

@@ -27,16 +27,17 @@ The main changes are:
     It also lists *all* migrations: both the ones available on disk as definition files, and the ones stored in the
     database (previously if you deleted a migration definition, it would just not be listed any more)
 
-* the `update` command has been renamed to `migrate` (but the previous name will be kept as alias for a while)
+* the `update` command has been renamed to `migrate` (but the previous name will be kept as alias for a while).
+
+* the `migrate` command now prevents concurrent execution of the same migration, stores in the database the reason of
+    failure of execution, warns of invalid migration definitions before execution, makes proper usage of database
+    transactions. It also has a new option to disable the wrapping of each migration in a database transaction and
+    probably more 
 
 * a new command `migration` is available. For the moment, it allows to delete existing migrations from the database
     table, making it possible to retry migrations which previously failed, as well as to manually add to the table
     migration definitions which are outside of the expected paths.
 
-* the `migrate` command now prevents concurrent execution of the same migration, stores in the database the reason of
-    failure of execution, warns of invalid migration definitions before execution, makes proper usage of database
-    transactions and probably more 
-
 * php migrations are now fully supported (they used to have naming problems fpr the generated php classes)
 
 * the validity of migration definition files is now checked before migration execution is attempted
@@ -46,7 +47,7 @@ The main changes are:
 * it is much easier now to extend the bundle, as proper Dependency Injection is used everywhere, as well as tagged services
 
 * the bundle is now tested on Travis, using eZPublish versions from 2014.3 to eZPlatform 1.4.0
-    (for the moment the testsuite is light, more tests will come in the future)
+    (for the moment the test suite is not 100% complete, more tests will come in the future)
 
 * changes to the YML definition language: