diff --git a/docs/web/cdist/update.mdwn b/docs/web/cdist/update.mdwn
index f3def316..1f8d03b4 100644
--- a/docs/web/cdist/update.mdwn
+++ b/docs/web/cdist/update.mdwn
@@ -14,6 +14,39 @@ If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
 The master branch on the other hand is the development branch and may not be
 working, break your setup or eat the tree in your garden.
 
+### Safely upgrading to new versions
+
+To upgrade to **any** further cdist version, you can take the
+following procedure to do a safe upgrade:
+
+    # Create new branch to try out the update
+    git checkout -b upgrade_cdist
+
+    # Get latest cdist version in git database
+    git fetch -v
+
+    # see what will happen on merge - replace
+    # master with the branch you plan to merge
+    git diff upgrade_cdist..origin/master
+
+    # Merge the new version
+    git merge origin/master
+
+Now you can ensure all custom types work with the new version.
+Assume that you need to go back to an older version during
+the migration/update, you can do so as follows:
+
+    # commit changes
+    git commit -m ...
+
+    # go back to original branch
+    git checkout master
+
+After that, you can go back and continue the upgrade:
+
+    # git checkout upgrade_cdist
+
+
 ## Update The Python Package
 
 To upgrade to the lastet version do