Merge pull request circleci#1150 from circleci/migrating-format-and-toc

Migrating format and toc

Author: michelle-luna

jekyll/_cci2/migrating-from-1-2.md

@@ -9,7 +9,10 @@ order: 15
 
 CircleCI 2.0 introduces the requirement that you create a configuration file (`.circleci/config.yml`), and it adds new required keys for which values must be defined. This release also allows you to use multiple jobs in your configuration. **Note:** If you configure multiple jobs, it is important to have parallelism set to `1` to prevent duplication of job runs.
 
-If you already have a `circle.yml` file, this article will help you add the new required keys and values and then search and replace your 1.0 keys with 2.0 keys. If you do not have a `circle.yml` file, refer to the [Sample 2.0 `config.yml` File]({{ site.baseurl }}/2.0/sample-config) to get started from scratch.
+If you already have a `circle.yml` file, this article will help you make a copy your exisiting file, create the new required keys, and then search and replace your 1.0 keys with 2.0 keys. If you do not have a `circle.yml` file, refer to the [Sample 2.0 `config.yml` File]({{ site.baseurl }}/2.0/sample-config) to get started from scratch.
+
+* Contents
+{:toc}
 
 ## Steps to Configure Required 2.0 Keys
 
@@ -55,13 +58,13 @@ Optionally configure workflows, using the following instructions:
 
 2. To persist a job artifact, add the `persist_to_workspace:<directory>` key at the end of the job, under `steps:`. Then, to get the saved artifact for use by another job, add the `attach_workspace:` key with a nested `at:<directory>` key, ideally  defined as the directory where the artifact was saved.
  
-3. Add lines for `workflows:`, `version: 2` and *<workflow_name>* at the *end* of the master `.circle/config.yml` file, replacing *<workflow_name>* with a unique name for your workflow. **Note:** The Workflows section of the `config.yml` file is not nested in the config. It is best to put the Workflows at the end of the file because the Workflows `version: 2` is in addition to the `version:` key at the top of the `config.yml` file during Beta. 
+3. As a best practice, add lines for `workflows:`, `version: 2` and `<workflow_name>` at the *end* of the master `.circle/config.yml` file, replacing `<workflow_name>` with a unique name for your workflow. **Note:** The Workflows section of the `config.yml` file is not nested in the config. It is best to put the Workflows at the end of the file because the Workflows `version: 2` is in addition to the `version:` key at the top of the `config.yml` file during Beta.  
      ```
      workflows:
        version: 2
        <workflow_name>:
      ```  
-4. Add a line for the `jobs:` key under <workflow_name> and add a list of all of the job names you want to orchestrate. In this example, `build` and `test` will run in parallel.
+4. Add a line for the `jobs:` key under `<workflow_name>` and add a list of all of the job names you want to orchestrate. In this example, `build` and `test` will run in parallel.
  
      ```
      workflows:
@@ -71,14 +74,26 @@ Optionally configure workflows, using the following instructions:
              - build
              - test
      ```  
-5. For Jobs which must run sequentially depending on success of another job, add the `requires:` key with a nested list of Jobs that must succeed for it to start. If you were using a `curl` command to start a Job, Workflows enable you to remove the command and start the job by using Workflows with the `requires:` key.
+5. For jobs which must run sequentially depending on success of another job, add the `requires:` key with a nested list of jobs that must succeed for it to start. If you were using a `curl` command to start a job, Workflows enable you to remove the command and start the job by using the `requires:` key.
  
      ```
-        - <job_name>
-	  requires:
-	     - <job_name>
+      - <job_name>
+          requires:
+            - <job_name>
+     ```
+6. For jobs which must run on a particular branch, add the `filters:` key with a nested `branches` and `only` key. For jobs which must not run on a particular branch, add the `filters:` key with a nested `branches` and `ignore` key.
+ 
      ```
-6. Validate your YAML again at <http://codebeautify.org/yaml-validator> to check the changes.
+     - <job_name>
+         filters:
+           branches:
+             only: master
+     - <job_name>
+         filters:
+           branches:
+             ignore: master
+     ```     
+7. Validate your YAML again at <http://codebeautify.org/yaml-validator> to check the changes.
 
 ## Search and Replace Deprecated 2.0 Keys