Merge branch 'master' into new-endpoint-for-trigger-workflows

Author: michelle-luna

.circleci/config.yml

@@ -62,7 +62,7 @@ jobs:
             - docs
   deploy:
     docker:
-      - image: cibuilds/aws:1.15.44
+      - image: cibuilds/aws:1.15.73
     steps:
       - attach_workspace:
           at: ./generated-site 

jekyll/_cci2/configuration-reference.md

@@ -1006,12 +1006,12 @@ ignore | N | String, or List of Strings | Either a single branch specifier, or a
 
 ###### **`tags`**
 {:.no_toc}
-CircleCI treats tag and branch filters differently when deciding whether a job should run.
 
-1. For a branch push unaffected by any filters, CircleCI runs the job.
-2. For a tag push unaffected by any filters, CircleCI skips the job.
-
-Item two above means that a job **must** have a `filters` `tags` section to run as a part of a tag push and all its transitively dependent jobs **must** also have a `filters` `tags` section. Refer to the [Git Tag Job Execution]({{ site.baseurl }}/2.0/workflows/#git-tag-job-execution) section of the Orchestrating Workflows document for more examples.
+CircleCI does not run workflows for tags
+unless you explicitly specify tag filters.
+Additionally,
+if a job requires any other jobs (directly or indirectly),
+you must specify tag filters for those jobs.
 
 Tags can have the keys `only` and `ignore` keys. You may also use regular expressions to match against tags by enclosing them with '/s', or map to a list of such strings. Regular expressions must match the **entire** string.
 
@@ -1027,6 +1027,8 @@ only | N | String, or List of Strings | Either a single tag specifier, or a list
 ignore | N | String, or List of Strings | Either a single tag specifier, or a list of tag specifiers
 {: class="table table-striped"}
 
+For more information,
+see the [Executing Workflows For a Git Tag]({{ site.baseurl }}/2.0/workflows/#executing-workflows-for-a-git-tag) section of the Workflows document.
 
 ###### *Example*
 

jekyll/_cci2/env-vars.md

@@ -372,7 +372,7 @@ Variable                    | Type    | Value
 `CIRCLE_PULL_REQUESTS`      | List    | Comma-separated list of URLs of the current build's associated pull requests.
 `CIRCLE_REPOSITORY_URL`     | String  | The URL of your GitHub or Bitbucket repository.
 `CIRCLE_SHA1`               | String  | The SHA1 hash of the last commit of the current build.
-`CIRCLE_TAG`                | String  | The name of the git tag, if the current build is tagged. For more information, see the [Git Tag Job Execution]({{ site.baseurl }}/2.0/workflows/#git-tag-job-execution).
+`CIRCLE_TAG`                | String  | The name of the git tag, if the current build is tagged. For more information, see the [Git Tag Job Execution]({{ site.baseurl }}/2.0/workflows/#executing-workflows-for-a-git-tag).
 `CIRCLE_USERNAME`           | String  | The GitHub or Bitbucket username of the user who triggered the build.
 `CIRCLE_WORKFLOW_ID`        | String  | A unique identifier for the workflow instance of the current job. This identifier is the same for every job in a given workflow instance.
 `CIRCLE_WORKING_DIRECTORY`  | String  | The value of the `working_directory` key of the current job.

jekyll/_cci2/executor-types.md

@@ -16,7 +16,7 @@ This document describes the `docker`, `machine`, and `macos` environments in the
 {:toc}
 
 ## Overview
-This version of CircleCI enables you to run jobs in one of three environments: using  Docker images, using a dedicated Linux VM image, or using a macOS VM image.
+This version of CircleCI enables you to run jobs in one of three environments: using Docker images, using a dedicated Linux VM image, or using a macOS VM image.
 
 For building on Linux, there are tradeoffs to `docker` versus `machine`, as follows:
 
@@ -61,7 +61,7 @@ In this example, all steps run in the container created by the first image liste
 
 More details on the Docker Executor are available in the [Configuring CircleCI]({{ site.baseurl }}/2.0/configuration-reference/) document.
 
-### Using Machine
+## Using Machine
 
 The `machine` option will run your jobs in a dedicated, ephemeral Virtual Machine (VM) with the following technical specifications:
 
@@ -111,7 +111,7 @@ jobs:
       docker_layer_caching: true    # default - false
 ```
 
-### Using macOS
+## Using macOS
 
 Using the `macos` executor allows you to run your job in a macOS environment on a VM. You can also specify which version of Xcode should be used. See the [Supported Xcode Versions section of the Testing iOS]({{ site.baseurl }}/2.0/testing-ios/#supported-xcode-versions) document for the complete list of version numbers. See the "Installed Software" links in that document for specific information about technical specifications (CPU, RAM, HD) for the VMs running each particular version of Xcode.
 

jekyll/_cci2/language-android.md

@@ -247,3 +247,7 @@ as you change code.
 CircleCI runs clean builds,
 so pre-dexing actually increases compilation time
 and may also increase memory usage.
+
+## Deployment
+
+See the [Deploy]({{ site.baseurl }}/2.0/deployment-integrations/) document for examples of deploy target configurations.

jekyll/_cci2/language-ruby.md

@@ -46,9 +46,8 @@ version: 2 # use CircleCI 2.0
 jobs: # a collection of steps
   build: # runs not using Workflows must have a `build` job as entry point
     parallelism: 3 # run three instances of this job in parallel
-    working_directory: ~/circleci-demo-ruby-rails # directory where steps will run
     docker: # run the steps with Docker
-      - image: circleci/ruby:2.4-node # ...with this image as the primary container; this is where all `steps` will run
+      - image: circleci/ruby:2.4.2-jessie-node # ...with this image as the primary container; this is where all `steps` will run
         environment: # environment variables for primary container
           BUNDLE_JOBS: 3
           BUNDLE_RETRY: 3
@@ -164,24 +163,31 @@ Directly beneath `working_directory`, you can specify container images under a `
 
 ```yaml
     docker:
-      - image: circleci/ruby:2.4-node
+      - image: circleci/ruby:2.4.2-jessie-node  # language image
         environment:
           BUNDLE_JOBS: 3
           BUNDLE_RETRY: 3
           BUNDLE_PATH: vendor/bundle
           PGHOST: 127.0.0.1
           PGUSER: circleci-demo-ruby
           RAILS_ENV: test
-      - image: circleci/postgres:9.5-alpine
+      - image: circleci/postgres:9.5-alpine  # service image
         environment:
           POSTGRES_USER: circleci-demo-ruby
           POSTGRES_DB: rails_blog
           POSTGRES_PASSWORD: ""
 ```
 
-The [official Ruby images](https://hub.docker.com/_/ruby/) are tagged to use the latest patch-level version of `2.4` and with additional packages installed for NodeJS.
+In this example,
+two [CircleCI convenience images]({{ site.baseurl }}/2.0/circleci-images/#image-types) are used:
 
-The [official Postgres image](https://hub.docker.com/_/postgres/) is specified for use as the database container.
+- A language image
+that runs on Debian Jessie
+and installs both Ruby 2.4.2 and Node.js.
+
+- A service image
+that runs on Alpine Linux
+and installs PostgreSQL 9.5.
 
 Then, several environment variables are added to connect the application container with the database for testing purposes. The `BUNDLE_*` environment variables are there to ensure proper caching and improve performance and reliability for installing dependencies with Bundler.
 
@@ -296,10 +302,6 @@ The `--profile` option reports the slowest examples of each run.
 
 For more on `circleci tests glob` and `circleci tests split` commands, please refer to our documentation on [Parallelism with CircleCI CLI](https://circleci.com/docs/2.0/parallelism-faster-jobs).
 
----
-
-Success! You just set up CircleCI 2.0 for a Ruby on Rails app. Check out our [Job page](https://circleci.com/gh/CircleCI-Public/circleci-demo-ruby-rails){:rel="nofollow"} to see how this looks when building on CircleCI.
-
 ## Deployment
 
 See the [Deploy]({{ site.baseurl }}/2.0/deployment-integrations/) document for examples of deploy target configurations.
@@ -311,7 +313,5 @@ This app illustrates the simplest possible setup for a Ruby on Rails web app. Re
 * [Discourse](https://github.com/CircleCI-Public/discourse/blob/master/.circleci/config.yml), an open source discussion platform.
 * [Sinatra](https://github.com/CircleCI-Public/circleci-demo-ruby-sinatra), a demo app for the [simple DSL for quickly creating web applications](http://www.sinatrarb.com/).
 
-
-
 [fork-demo-project]: https://github.com/CircleCI-Public/circleci-demo-ruby-rails/fork
 [rspec-junit-formatter]: https://github.com/sj26/rspec_junit_formatter

jekyll/_cci2/workflows-overview.md

@@ -12,7 +12,7 @@ CircleCI [Workflows]({{ site.baseurl }}/2.0/workflows/) enable you to sequence a
 
 Holding a Workflow for Manual Approval     |  Using Filters
 ----------------------------|----------------------
-Add an [approval job]({{ site.baseurl }}/2.0/workflows/#holding-a-workflow-for-a-manual-approval) to set up a manual gate.      |   Use [regex]({{ site.baseurl }}/2.0/workflows/#regular-expression-support) to [filter on branches]({{ site.baseurl }}/2.0/workflows/#branch-level-job-execution) or [filter on tags]({{ site.baseurl }}/2.0/workflows/#git-tag-job-execution).  
+Add an [approval job]({{ site.baseurl }}/2.0/workflows/#holding-a-workflow-for-a-manual-approval) to set up a manual gate.      |   Use [regex]({{ site.baseurl }}/2.0/workflows/#using-regular-expressions-to-filter-tags-and-branches) to [filter on branches]({{ site.baseurl }}/2.0/workflows/#branch-level-job-execution) or [filter on tags]({{ site.baseurl }}/2.0/workflows/#executing-workflows-for-a-git-tag).  
 
 <hr>
 

jekyll/_cci2/workflows.md

@@ -268,7 +268,7 @@ workflows:
             - test2
 ```
 
-The environment variables are defined by setting the `context` key as shown to the default name `org-global`. The `test1` and `test2` jobs in this workflows example will use the same shared environment variables when initiated by a user who is part of the organization. By default, all projects in an organization have access to contexts set for that organization. 
+The environment variables are defined by setting the `context` key as shown to the default name `org-global`. The `test1` and `test2` jobs in this workflows example will use the same shared environment variables when initiated by a user who is part of the organization. By default, all projects in an organization have access to contexts set for that organization.
 
 ### Branch-Level Job Execution
 The following example shows a workflow configured with jobs on three branches: Dev, Stage, and Pre-Prod. Workflows will ignore `branches` keys nested under `jobs` configuration, so if you use job-level branching and later add workflows, you must remove the branching at the job level and instead declare it in the workflows section of your `config.yml`, as follows:
@@ -277,15 +277,15 @@ The following example shows a workflow configured with jobs on three branches: D
 
 The following `config.yml` snippet is an example of a workflow configured for branch-level job execution:
 
-```
+```yaml
 workflows:
   version: 2
   dev_stage_pre-prod:
     jobs:
       - test_dev:
-          filters:
+          filters:  # using regex filters requires the entire branch to match
             branches:
-              only:
+              only:  # only branches matching the below regex filters will run
                 - dev
                 - /user-.*/
       - test_stage:
@@ -298,64 +298,53 @@ workflows:
               only: /pre-prod(?:-.+)?$/
 ```
 
-In the example, `filters` is set with the `branches` key and the `only` key with the branch name. Any branches that match the value of `only` will run the job. Branches matching the value of `ignore` will not run the job. See the [Sample Sequential Workflow config with Branching](https://github.com/CircleCI-Public/circleci-demo-workflows/blob/sequential-branch-filter/.circleci/config.yml) for a full example.
-
-### Git Tag Job Execution
+For more information on regular expressions,
+see the [Using Regular Expressions to Filter Tags And Branches](#using-regular-expressions-to-filter-tags-and-branches) section below.
+For a full example of workflows,
+see the [configuration file](https://github.com/CircleCI-Public/circleci-demo-workflows/blob/sequential-branch-filter/.circleci/config.yml) for the Sample Sequential Workflow With Branching project.
 
-CircleCI treats tag and branch filters differently when deciding whether a job should run.
+### Executing Workflows for a Git Tag
 
-1. For a branch push unaffected by any filters, CircleCI runs the job.
-2. For a tag push unaffected by any filters, CircleCI skips the job.
+CircleCI does not run workflows for tags
+unless you explicitly specify tag filters.
+Additionally,
+if a job requires any other jobs (directly or indirectly),
+you must [use regular expressions](#using-regular-expressions-to-filter-tags-and-branches)
+to specify tag filters for those jobs.
 
-Item two above means that a job **must** have a `filters` `tags` section to run as a part of a tag push and all its transitively dependent jobs **must** also have a `filters` `tags` section. 
+In the example below,
+two workflows are defined:
 
-Following is a very basic example for building any branch and using tags. The regular expression is a full match rather than a partial match. For example, `only: /^config-test.*/` matches any tag with the prefix `config-test-111` and `only: /^config-test/` matches all tags that match `config-test`.  To match the common use case of a semantic versioning, for example, use `/version-2\.1\.[3-7]/` to match `version-2.1.`(3 through 7).
+- `untagged-build` runs the `build` job for all branches.
+- `tagged-build` runs `build` for all branches **and** all tags starting with `v`.
 
-
-```
+```yaml
 workflows:
   version: 2
-  un-tagged-build:
+  untagged-build:
     jobs:
-      - build:
-          filters:
-            tags:
-              ignore: /^v.*/
+      - build
   tagged-build:
-    jobs:
-      - build:
-          filters:
-            branches:
-              ignore: /.*/
-	    tags:
-	      only: /^v.*/
-```
-
-The following `build` job example will run for all branches, and all tags, except those starting with `testing-`.
-
-```
-workflows:
-  version: 2
-  build-workflow:
     jobs:
       - build:
           filters:
             tags:
-              ignore: /^testing-.*/
+              only: /^v.*/
 ```
 
-The following example runs 
+In the example below,
+two jobs are defined within the `build-n-deploy` workflow:
 
-1. `build` job for all branches, and all tags.
-2. `deploy` job only for tags marked with a version number.
+- The `build` job runs for all branches and all tags.
+- The `deploy` job runs for no branches and only for tags starting with 'v'.
 
-```
+```yaml
 workflows:
   version: 2
   build-n-deploy:
     jobs:
       - build:
-          filters:
+          filters:  # required since `deploy` has tag filters AND requires `build`
             tags:
               only: /.*/
       - deploy:
@@ -368,26 +357,26 @@ workflows:
               ignore: /.*/
 ```
 
-**Note:** The `build` job **must** also have a `filters` `tags` section, as it is a transient dependency of the `deploy` job.
-
-The following example runs
+In the example below,
+three jobs are defined with the `build-test-deploy` workflow:
 
-1. `build` and `test` jobs for all branches and only `config-test.*` tags.
-2. `deploy` only for `config-test.*` tags.
+- The `build` job runs for all branches and only tags starting with 'config-test'.
+- The `test` job runs for all branches and only tags starting with 'config-test'.
+- The `deploy` job runs for no branches and only tags starting with 'config-test'.
 
-```
+```yaml
 workflows:
   version: 2
-  build-n-deploy:
+  build-test-deploy:
     jobs:
       - build:
-          filters:
+          filters:  # required since `test` has tag filters AND requires `build`
             tags:
               only: /^config-test.*/
       - test:
           requires:
             - build
-          filters:
+          filters:  # required since `deploy` has tag filters AND requires `test`
             tags:
               only: /^config-test.*/
       - deploy:
@@ -398,14 +387,31 @@ workflows:
               only: /^config-test.*/
             branches:
               ignore: /.*/
-
 ```
 
-**Note:** Webhook payloads from GitHub [are capped at 5MB](https://developer.github.com/webhooks/#payloads) and [for some events](https://developer.github.com/v3/activity/events/types/#createevent) a maximum of 3 tags. This means that if you push a lot of tags we may not receive all of them.
-
-### Regular Expression Support
-
-CircleCI branch and tag filters support the Java variant of regex pattern matching, see the [java.util.regex documentation](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html) for details. 
+**Note:**
+Webhook payloads from GitHub [are capped at 5MB](https://developer.github.com/webhooks/#payloads)
+and [for some events](https://developer.github.com/v3/activity/events/types/#createevent) a maximum of 3 tags.
+If you push several tags at once,
+CircleCI may not receive all of them.
+
+### Using Regular Expressions to Filter Tags and Branches
+
+CircleCI branch and tag filters support
+the Java variant of regex pattern matching.
+When writing filters,
+CircleCI matches exact regular expressions.
+
+For example,
+`only: /^config-test/` only matches the `config-test` tag.
+To match all tags starting with `config-test`,
+use `only: /^config-test.*/` instead.
+Using tags for semantic versioning is a common use case.
+To match patch versions 3-7 of a 2.1 release,
+you could write `/^version-2\.1\.[3-7]/`.
+
+For full details on pattern-matching rules,
+see the [java.util.regex documentation](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html).
 
 ## Using Workspaces to Share Data Among Jobs