diff --git a/README.rst b/README.rst
index 8ffeab8..973164f 100644
--- a/README.rst
+++ b/README.rst
@@ -231,6 +231,50 @@
 to our shutdown script - but that would break any other Erlang apps
 running on the system; it's more "global" than RabbitMQ.
 
+Upgrades
+========
+
+The rabbitmq formula provide set of phases (logical bloks) that will help to
+build flexible upgrade orchestration logic for particular components. The list
+of phases might and theirs descriptions are listed in table below:
+
++-------------------------------+------------------------------------------------------+
+| State                         | Description                                          |
++===============================+======================================================+
+| <app>.upgrade.service_running | Ensure that all services for particular application  |
+|                               | are enabled for autostart and running                |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.service_stopped | Ensure that all services for particular application  |
+|                               | disabled for autostart and dead                      |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.pkgs_latest     | Ensure that packages used by particular application  |
+|                               | are installed to latest available version.           |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.render_config   | Ensure configuration is rendered actual version.     +
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.pre             | We assume this state is applied on all nodes in the  |
+|                               | cloud before running upgrade.                        |
+|                               | Only non destructive actions will be applied during  |
+|                               | this phase. Perform service built in service check   |
+|                               | like (rabbitmqctl cluster_status)                    |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.upgrade.pre     | Do nothing for now                                   |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.upgrade         | This state will basically upgrade application on     |
+|                               | particular target. Stop services, render             |
+|                               | configuration, install new packages, start services  |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.upgrade.post    | Do nothing for now                                   |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.post            | This phase should be launched only when upgrade of   |
+|                               | the cloud is completed. Cleanup temporary files,     |
+|                               | perform other post upgrade tasks.                    |
++-------------------------------+------------------------------------------------------+
+| <app>.upgrade.verify          | Verify current node is present in running_nodes on   |
+|                               | the cluster.                                         |
++-------------------------------+------------------------------------------------------+
+
+
 Read more
 =========