add target version and rollback config examples

Author: rosieyohannan

docs/guides/modules/deploy/pages/configure-deploy-markers.adoc

@@ -16,83 +16,58 @@ For a full guide to CircleCI's deploys features and functionality, refer to the
 * 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. Create an envrionment
-
-Our first step is to create an environment and component for your deployment. You can choose to skip this step if either of the following is true:
-
-* You already have an environment set up in your organization.
-* You are happy for CircleCI to automatically create an environment with the name `default` and a component with the name of your project.
-
-=== 1.1 Create an 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. 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].
-
-=== 1.2
-
-== 2. Update the configuration
+== 1. Update the configuration
 
 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.
 
-=== 2.1. Plan a deploy
+=== 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 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`.
 
-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.
+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 already have multiple environments and components you must specify their names manually, as follows:
+==== Examples for target-version
 
+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 <deploy-name> --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 configuraiton 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 and named `default`.
-** 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:
-
+* Anothe 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`.
-
-=== 2.2. Update the deploy status
+=== 1.2. Update the deploy status
 
 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.
 
@@ -163,7 +138,7 @@ 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.
 
-=== 2.3 Update the deploy status to canceled
+=== 1.3 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.
 
@@ -293,10 +268,26 @@ 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
+
+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.
+
+=== Create an 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. 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].
+
 == Manual configuration of automatically detected deploys
 
 If you have some link:https://circleci.com/changelog/auto-generated-deploy-markers-are-being-sunset/[automatically detected deploy markers] you can consider manually configuring them. CircleCI no longer automatically creates deploy markers for you.