Deploys docs improvements

- Consolidate rollback docs into one page
- Consolidate deployment and deploy overview pages into one page
- Clarify applications for each method along with advantages and disadvantages
- Update deploy markers page to make steps more clear

Author: pete-woods

docs/guides/modules/deploy/pages/rollback-a-project-by-workflow-rerun.adoc renamed to archive/rollback-a-project-by-workflow-rerun.adoc

@@ -161,19 +161,16 @@
 *** xref:test:troubleshoot-test-splitting.adoc[Troubleshoot test splitting]
 
 * Deploy with CircleCI
-** xref:deploy:deployment-overview.adoc[Overview of deployment on CircleCI]
-** xref:deploy:deploys-overview.adoc[CircleCI deploys overview]
+** xref:deploy:deployment-overview.adoc[Deployment and deploy management]
+** Setup
+*** xref:deploy:configure-deploy-markers.adoc[Configure deploy markers]
+*** xref:deploy:set-up-rollbacks.adoc[Rollbacks]
 ** Release agent setup
 *** xref:deploy:set-up-circleci-deploys.adoc[Set up CircleCI deploys]
 *** xref:deploy:set-up-the-release-agent.adoc[Set up the release agent]
 *** xref:deploy:configure-your-kubernetes-components.adoc[Configure your Kubernetes components]
 *** xref:deploy:update-the-kubernetes-release-agent.adoc[Update the Kubernetes release agent]
 *** xref:deploy:manage-deploys.adoc[Manage deploys]
-** Agentless setup
-*** xref:deploy:configure-deploy-markers.adoc[Configure deploy markers]
-*** xref:deploy:set-up-rollbacks.adoc[Set up rollbacks in CircleCI]
-*** xref:deploy:rollback-a-project-using-the-rollback-pipeline.adoc[Rollback a project using the rollback pipeline]
-*** xref:deploy:rollback-a-project-by-workflow-rerun.adoc[Rollback a project by workflow rerun]
 ** How-to guides
 *** xref:deploy:deploy-to-amazon-sagemaker.adoc[Deploy to Amazon SageMaker]
 *** xref:deploy:deploy-android-applications.adoc[Deploy Android applications]

docs/guides/modules/deploy/pages/rollback-a-project-using-the-rollback-pipeline.adoc renamed to archive/rollback-a-project-using-the-rollback-pipeline.adoc

@@ -9,70 +9,72 @@ This tutorial shows how to add a deploy marker step to your workflow config. Dep
 
 Deploy markers provide a lightweight way to log your deployments without requiring a you to install the CircleCI release agent. If you install deploy markers, as described in this guide, you will also be able to use the xref:set-up-rollbacks.adoc[CircleCI rollback feature].
 
-For a full guide to CircleCI's deploys features and functionality, refer to the xref:set-up-circleci-deploys.adoc[Set up CircleCI deploys] guide.
+For a full guide to CircleCI's deploys features and functionality, refer to the xref:deployment-overview.adoc[Deployment and deploy management] guide.
+
+You can configure deploy markers as follows:
+
+* To display updated statuses depending of the outcome of your deployments. Steps for this are provided in the <<deploy-markers-with-status-updates>> section.
+* Or, you can choose to configure deploy markers to log deployments without status updates. Steps for this are provided in the <<deploy-logs-without-status-updates>> section.
 
 == Prerequisites
 
 * A CircleCI account connected to your code. You can link:https://circleci.com/signup/[sign up for free].
 * A CircleCI project with a workflow configured to deploy your code.
 
-== 1. Update the configuration
+== Deploy markers with status updates
 
 To create a deployment marker, you will update your CircleCI configuration file.
+
 You will add commands to plan a deploy and then update its status based on the outcome of your deployment script.
 
+NOTE: The `circleci run release` commands are only available in CircleCI builds and are not part of the CircleCI local CLI. You do not need to install the CircleCI local CLI in your CircleCI pipeline to use these commands.
+
 === 1.1. Plan a deploy
 
 Add a `circleci run release plan` command to your deployment job. This tells CircleCI to plan a new deploy and show it in the link:https://app.circleci.com/deploys[Deploys UI] with `pending` status.
-The `target-version` parameter should match the name of the version being deployed.
 
 [,yml]
 ----
 jobs:
   deploy-my-service:
     executor: some-executor
     steps:
-      - run: circleci run release plan --target-version=<some-version-name>
+      - run: circleci run release plan <deploy-name> --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name> --namespace=<some-namespace>
 ----
 
-If you do not have an environment set up in your organization a new one will be created with the name `default`. This will be set as the target for this deploy. See <<manage-environments>> for more information.
+In this example, note the following flags and options:
+
+* The `deploy-name` parameter is used to identify the deployment. `deploy-name` is an arbitrary positional argument that will be used to identify the deployment and should be unique within the workflow. If not specified, the deployment name will be set to `default`. If you are deploying multiple components or to multiple environments from a single workflow, you need to provide the command with a deployment name.
+* The `environment-name` parameter sets the target environment. If the specified environment does not exist, it will be created. If you do not specify an environment, CircleCI will create one named `default`.
+* The `component-name` parameter sets the name that will be displayed in the Deploys UI. If you do not already have a component in your project a new one will be created with the name of the project. This will be set as the component that is being deployed.
+* The `target-version` parameter should match the version being deployed. Some examples are provided <<examples-for-target-version,in the next section>>.
+* The `namespace` parameter is optional and can be provided to use a value other than `default`.
+
+Configuring `circleci run release plan` identifies the deployment you are planning so that you can reference it to update its status later on.
 
-If you do not already have a component in your project a new one will be created with the name of the project. This will be set as the component that is being deployed.
+==== Examples for target-version
 
-If you already have multiple environments and components you must specify their names manually, as follows:
+This section provides some options for setting the `target-version` parameter.
 
+* One option is to use CircleCI's built-in environment variables. For example you could define the target version as follows:
++
 [,yml]
 ----
-jobs:
-  deploy-my-service:
-    executor: some-executor
-    steps:
-      - run: circleci run release plan --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name> --namespace=<some-namespace>
+--target-version="1.0.${CIRCLE_BUILD_NUM}-${CIRCLE_SHA1:0:7}"
 ----
++
+This configuration would yield a value with the following format `1.0.28853-ffdbeb1`.
 
-In this example, note the following:
-
-** The `environment-name` parameter sets the target environment. If the specified environment does not exist, it will be created.
-** The `component-name` parameter sets the name that will be displayed in the Deploys UI.
-** The `namespace` parameter is optional and can be provided to use a value other than `default`.
-
-If you are deploying multiple components or to multiple environments from a single workflow, you need to provide the command with a deployment name.
-This identifies the deployment your are planning so that you can later on reference it to update its status.
-This can be done as shown below:
-
+* Another option is to use pipeline values. For example you could define the target version as follows:
++
 [,yml]
 ----
-jobs:
-  deploy-my-service:
-    executor: some-executor
-    steps:
-      - run: circleci run release plan <deploy-name> --environment-name=<some-environment-name> --component-name<=>some-component-name> --target-version=<some-version-name>
+--target-version=<< pipeline.number >>
 ----
++
+This configuration would yield a value with the following format `12345`.
 
-In the example the positional argument `deploy-name` is the arbitrary value that will be used to identify the deployment and should be unique within the workflow.
-If not specified, the deployment name will be set to `default`.
-
-=== 1.2. Update the deploy status
+=== 1.2. Update the deploy status to running
 
 After deploying your application, you can update the status of the deployment to `RUNNING` by running the `circleci run release update` command in a new step.
 
@@ -88,8 +90,7 @@ jobs:
       - run: circleci run release update --status=running
 ----
 
-If you are deploying multiple components or to multiple environments from a single workflow, you need to provide the command with a deployment name.
-This value should match the value you provided when you planned the deploy.
+If you are deploying multiple components or to multiple environments from a single workflow, you need to provide the command with a deployment name. The deploy name value should match the value you provided when you planned the deploy.
 
 [,yml]
 ----
@@ -103,8 +104,10 @@ jobs:
       - run: circleci run release update <deploy-name> --status=running
 ----
 
-Now you can use the `when` attribute to add `on_success` and `on_failure` steps at the end of your deployment job, to handle the final status update of the deploy.
+=== 1.3. Update the deploy status to success or failure
+You can use the `when` attribute to add `on_success` and `on_failure` steps at the end of your deployment job, to handle the final status update of the deploy.
 
+.Config file example showing deploy status update to success or failure
 [,yml]
 ----
 jobs:
@@ -132,21 +135,23 @@ jobs:
           when: on_fail
 ----
 
-This will update the status of the deploy to `SUCCESS` or `FAILED` depending on the outcome of your job.
-In this example, the `failure_reason.env` file can be created by a previous step in the job. This can be done, for example, in a step in which we are validating the status of the deployment.
-You can do that as shown below:
+In this example, the status of the deploy is updated to `SUCCESS` or `FAILED` depending on the outcome of your job.
+
+The `failure_reason.env` file can be created by a previous step in the job. This can be done, for example, in a step in which we are validating the status of the deployment. One way to do this is as follows:
 
+.Create a file to store the failure reason
 [,yml]
 ----
 echo "FAILURE_REASON='Deployment was not found'" > failure_reason.env
 ----
 
 CAUTION: Trying to update the status of the deploy after updating it to a terminal status such as `SUCCESS`, `FAILED` or `CANCELED` is not supported and will result in an error.
 
-=== 1.3 Update the deploy status to canceled
+=== 1.4 Update the deploy status to canceled
 
 If you want to update your deployment to `canceled` when the deploy job is canceled, you can do so by adding the following job to your configuration.
 
+.Job configuration for updating the deploy status to canceled
 [,yml]
 ----
 jobs:
@@ -166,6 +171,7 @@ jobs:
 
 Then you can add it to your workflow as shown below.
 
+.Workflow configuration for updating the deploy status to canceled. The cancel-deploy job only runs when the deploy job is canceled
 [,yml]
 ----
 workflows:
@@ -178,9 +184,9 @@ workflows:
               - canceled
 ----
 
-This will make it sot that the job will be run only when the `deploy` job is canceled, thus updating the deployment to the `canceled` status.
+In this example, the `cancel-deploy` job will be run only when the `deploy` job is canceled, thus updating the deployment to the `canceled` status.
 
-=== 1.4. Full config example
+=== 1.5. Full config example
 
 For reference, here is a full example of a CircleCI config that makes use of the deployment tracking feature.
 
@@ -239,7 +245,7 @@ workflows:
               - canceled
 ----
 
-== 2. Deploy logs
+== Deploy logs without status updates
 
 Sometimes you might not want your deployment marker to have any specific status, but still want it to be logged in the deploys UI.
 In those cases you can use the `release log` command in place of `release plan` as shown in the example below.
@@ -273,29 +279,30 @@ jobs:
 
 ** The `environment-name` specifies the target environment. If the environment does not exist, it will be created.
 ** The `component-name` parameter sets the name that will be displayed in the CircleCI UI.
-** The `target-version` parameter should match the name of the version being deployed.
+** The `target-version` parameter should match the name of the version being deployed. Some examples are provided <<examples-for-target-version,above>>.
 ** (Optional) You can provide the following parameter if required:
 *** The `namespace` parameter can be provided to use a value other than `default`.
 
-[#manage-environments]
-== 3. Manage environments
+== Manage environments
+
+In this guide we created an environment integration by supplying a name with the `--envionment-name` flag. This was an optional step. If you did not specify an environment CircleCI will have created one for you with the name `default`.
+
+You can also create an environment integration manually in the CircleCI web app.
 
-Configuring deploy markers will automatically create an environment integration in the link:https://app.circleci.com/deploys[CircleCI deploys UI] with the name you specified or with the `default` name if you didn't specify any.
-You can then use the link:https://app.circleci.com/deploys/github/circleci#environments[CircleCI UI] to manage your environments, by creating, deleting or updating them.
-To manually create an environment integration, follow these steps:
+=== Create an environment integration
 
-. In the CircleCI web app, select **Deploys** in the sidebar.
-. If this is your first environment setup, select btn:[Create your first Environment Integration]. If you already have environments set up, choose the **Environments** tab and select btn:[Create Environment Integration].
+. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
+. Select **Deploys** in the sidebar.
+. Select the **Environments** tab.
+. Select btn:[Create Environment Integration].
 . Enter a name for your environment, and a description if you would like.
-. Use the dropdown menu to choose your environment integration type, then select btn:[Next: Release Agent Setup].
-If you plan to only use deploy markers, as opposed to the Kubernetes agent, feel free to choose the `custom` type.
-**You do not need to continue with installing a release agent at this point**, but you will need to reference this environment integration name as part of your config when adding the `log release` step below.
+. Use the dropdown menu to choose your environment integration type. Choose the "Custom" option to follow along with this guide,. If you are deploying to your Kubernetes cluster you can or if you want to use the CircleCI release agent, then choose "Kubernetes Cluster" and head over to the xref:set-up-circleci-deploys.adoc[Release agent setup] page.
+. Select btn:[Save and Continue].
 
 == Next steps
 
 By following the steps in this guide, you have added a deploy marker to your CircleCI configuration.
 You can now track the status of your deployments across your configured environments in the CircleCI deploys UI and in the project home page.
 You can now:
 
-* xref:set-up-the-release-agent.adoc[Set up a release agent on your Kubernetes cluster].
-* xref:configure-deploy-markers.adoc[Learn about deploy markers]
+* xref:set-up-rollbacks.adoc[Set up rollbacks].