Upgrading: refresh information, reorganize the page

doc/05-Upgrading.md

@@ -1,47 +1,39 @@
 <a id="Upgrading"></a>Upgrading
 ===============================
 
-Icinga Director is very upgrade-friendly. Drop the new version to your Icinga
+Icinga Director is very upgrade-friendly. We never had any complaint referring
-Web 2 module folder and you're all done. In case you make use of the
+data loss on upgrade. But to be on the safe side, please always [backup](#backup-first)
-[Job Runner](79-Jobs.md), you should restart it's service. Eventually refresh
+your database before running an upgrade.
-the page in your browser<sup>[[1]](#footnote1)</sup>, and you are ready to go.
-Should there any other actions be required, you will be told so in your frontend.
 
-Read more about:
+Then drop the new version to your Icinga Web 2 module folder and you're all done.
+In case you make use of the [Job Runner](79-Jobs.md), you should restart it's
+service. Eventually refresh the page in your browser<sup>[[1]](#footnote1)</sup>,
+and you are ready to go.
 
-* [How to work with the latest GIT master](#git-master)
+Should there any other actions be required (like [schema migrations](#schema-migrations)),
+you will be told so in your frontend.
+
+Please read more about:
+
+* [Database Backup](#backup-first)
+* [Upgrading to 1.3.0](#upgrade-to-1.3.0)
 * [Upgrading to 1.2.0](#upgrade-to-1.2.0)
 * [Upgrading to 1.1.0](#upgrade-to-1.1.0)
+* [How to work with the latest GIT master](#git-master)
 * [Database schema upgrades](#schema-migrations)
 * [Job Runner restart](#restart-jobrunner)
+* [Downgrading](#downgrade)
 
 And last but not least, having a look at our [Changelog](82-Changelog.md) is
-always a good idea before an upgrade.
+usually a good idea before applying an upgrade.
 
-<a name="git-master"></a>Work with the latest GIT master
+<a name="backup-first"></a>Always take a backup first
---------------------------------------------------------
+-----------------------------------------------------
 
-Icinga Director is still a very young project. Lots of changes are going on,
+All you need for backing up your Director is a snapshot of your database. Please
-a lot of improvements, bug fixes and new features are still being added every
+use the tools provided by your database backend, like `mysqldump` or `pg_dump`.
-month. People living on the bleeding edge might prefer to use all of them as
+Restoring from a backup is trivial, and Director will always be able to apply
-soon as possible.
+pending database migrations to an imported old database snapshot.
-
-So here is the good news: this is no problem at all. It's absolutely legal and
-encouraged to run Director as a pure GIT clone, installed as such:
-
-```sh
-ICINGAWEB_MODULES=/usr/share/icingaweb2/modules
-DIRECTOR_GIT=https://github.com/Icinga/icingaweb2-module-director.git
-git clone $DIRECTOR_GIT $ICINGAWEB_MODULES/director
-```
-
-Don't worry about schema upgrades. Once they made it into our GIT master there
-will always be a clean upgrade path for you, no manual interaction should ever
-be required. Like every human being, we are not infallible. So, while our strict
-policy says that the master should never break, this might of course happen.
-
-In that case, please [let us know](https://dev.icinga.org/projects/icingaweb2-module-director/issues)
-We'll try to fix your issue as soon as possible. 
 
 <a name="upgrade-to-1.3.0"></a>Upgrading to 1.3.0
 -------------------------------------------------
@@ -73,6 +65,31 @@ GIT master since then, all you need is to replace the Director module folder wit
 the new one. Or to run `git checkout v1.1.0` in case you installed Director from
 GIT.
 
+<a name="git-master"></a>Work with the latest GIT master
+--------------------------------------------------------
+
+Icinga Director is still a very young project. Lots of changes are going on,
+a lot of improvements, bug fixes and new features are still being added every
+month. People living on the bleeding edge might prefer to use all of them as
+soon as possible.
+
+So here is the good news: this is no problem at all. It's absolutely legal and
+encouraged to run Director as a pure GIT clone, installed as such:
+
+```sh
+ICINGAWEB_MODULES=/usr/share/icingaweb2/modules
+DIRECTOR_GIT=https://github.com/Icinga/icingaweb2-module-director.git
+git clone $DIRECTOR_GIT $ICINGAWEB_MODULES/director
+```
+
+Don't worry about schema upgrades. Once they made it into our GIT master there
+will always be a clean upgrade path for you, no manual interaction should ever
+be required. Like every human being, we are not infallible. So, while our strict
+policy says that the master should never break, this might of course happen.
+
+In that case, please [let us know](https://dev.icinga.com/projects/icingaweb2-module-director/issues)
+We'll try to fix your issue as soon as possible.
+
 <a name="schema-migrations"></a>Database schema migrations
 ----------------------------------------------------------
 
@@ -82,6 +99,24 @@ applied with a single click. And if your Director is deployed automatically by
 and automation tool like Puppet, also schema upgrades can easily be handled
 that way. Just follow the [related examples](03-Automation.md) in our documentation.
 
+<a name="schema-migrations"></a>Manual schema migrations
+----------------------------------------------------------
+
+Please *do not* manually apply our schema migration files. We are very strict
+about our connection settings, encodings and SQL modes. Client encoding MUST be
+UTF-8, for MySQL and MariaDB we are using the following SQL Mode:
+
+```sql
+SET SESSION SQL_MODE='STRICT_ALL_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
+ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,ANSI_QUOTES,PIPES_AS_CONCAT,
+NO_ENGINE_SUBSTITUTION';
+```
+
+Our migration files are written based on the assumption that those rules are
+strictly followed, and there may be other ones in future. So please use one
+of the supported migration methods either on the web or on command line and
+stay away from directly interfering with the schema.
+
 <a name="restart-jobrunner"></a>Restart the Job Runner service
 --------------------------------------------------------------
 
@@ -94,6 +129,14 @@ even when it's just a quick `git pull`:
 systemctl restart director-jobs.service
 ```
 
+<a name="downgrade"></a>Downgrading
+-----------------------------------
+
+Downgrading is **not supported**. Most parts of the code will even refuse to
+work in case there are new fields in their database tables. Migrations are
+intentionally provided for upgrades only. In case you want to travel back in
+time please restore a matching former [Database Backup](#backup-first).
+
 <a name="footnote1">[1]</a>:
 Future Icinga Web 2 version will also take care of this step. We want to be
 able to have the latest JavaScript and CSS for any active module to be shipped