[DOCS] Drafts docs for Upgrade Transforms API

docs/reference/transform/apis/index.asciidoc

@@ -13,5 +13,6 @@ include::preview-transform.asciidoc[leveloffset=+2]
 include::start-transform.asciidoc[leveloffset=+2]
 //STOP
 include::stop-transform.asciidoc[leveloffset=+2]
-//UPDATE
-include::update-transform.asciidoc[leveloffset=+2]
+//UPDATE-UPGRADE
+include::update-transform.asciidoc[leveloffset=+2]
+include::upgrade-transforms.asciidoc[leveloffset=+2]

docs/reference/transform/apis/upgrade-transforms.asciidoc

@@ -1,14 +1,14 @@
 [role="xpack"]
 [testenv="basic"]
 [[upgrade-transforms]]
-= Upgrade {transform} API
+= Upgrade {transforms} API
 
 [subs="attributes"]
 ++++
-<titleabbrev>Upgrade {transform}</titleabbrev>
+<titleabbrev>Upgrade {transforms}</titleabbrev>
 ++++
 
-Upgrades all {transform}s.
+Upgrades all {transforms}.
 
 [[upgrade-transforms-request]]
 == {api-request-title}
@@ -29,24 +29,54 @@ Requires the following privileges:
 [[upgrade-transforms-desc]]
 == {api-description-title}
 
-This API upgrades all existing {transform}s.
+
+
+This API upgrades all existing {transforms} that are necessary to be upgraded.
+{transforms-cap} are compatible between different versions and backwards 
+compatibility is kept between major versions. However, it is still necessary to 
+upgrade them to meet functional requirements. Upgrading {transforms} might also 
+enable new features or improve performance.
+
+During upgrade, the {transforms} are rewritten into the latest format including 
+internal data structures that store state and checkpoints. Resources are also 
+freed up by cleaning up previous versions.
+
+If an upgrade step fails, the process stops, and an error is returned that 
+informs about the underlying issues. It might be necessary to manually resolve 
+the problems then the process can be re-run again. A summary is returned when 
+the upgrade is finished.
+
+[IMPORTANT]
+====
+
+* When {es} {security-features} are enabled, your {transform} remembers the 
+roles of the user who created or updated it last. In contrast to 
+<<update-transform,update transform>>, upgrade {transforms} does not change the 
+stored roles, therefore it needs to be run by a super user.
+
+====
+
 
 [[upgrade-transforms-query-parms]]
 == {api-query-parms-title}
 
 `dry_run`::
-  (Optional, Boolean) When `true`, only checks for updates but does not execute them.
+  (Optional, Boolean) When `true`, only checks for updates but does not execute 
+  them. Defaults to `false`.
+
 
 [[upgrade-transforms-example]]
 == {api-examples-title}
 
+To upgrade the {transforms}, perform the following API call:
+
 [source,console]
 --------------------------------------------------
 POST _transform/_upgrade
 --------------------------------------------------
 // TEST[setup:simple_kibana_continuous_pivot]
 
-When all {transform}s are upgraded, you receive a summary:
+When all {transforms} are upgraded, you receive a summary:
 
 [source,console-result]
 ----