chore: issue 487. clarify "named" branches vs. others (#553)

* chore: issue 487. Adding info on named branches.

* chore: issue 487. Testing comment.

* chore: issue 487. Updating rest of readmes.

* chore: per morgante's comment

* chore: changing to "named environment branch" everywhere

1-org/README.md

@@ -169,12 +169,15 @@ Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to see
    git add .
    git commit -m 'Your message'
    ```
-1. Push your plan branch to trigger a plan. For this command, the branch `plan` is not a special one. Any branch which name is different from `development`, `non-production` or `production` will trigger a Terraform plan.
+1. Push your plan branch to trigger a plan for all environments. Because the
+   _plan_ branch is not a [named environment branch](./docs/FAQ.md), pushing your _plan_
+   branch triggers _terraform plan_ but not _terraform apply_.
    ```
    git push --set-upstream origin plan
    ```
 1. Review the plan output in your Cloud Build project. https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to production branch.
+1. Merge changes to production branch.  Because the _production_ branch is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b production
    git push origin production
@@ -239,7 +242,7 @@ to run the command as the Terraform service account.
    git add .
    git commit -m 'Your message'
    ```
-1. Push your plan branch. The branch `plan` is not a special one. Any branch which name is different from `development`, `non-production` or `production` will trigger a Terraform plan.
+1. Push your plan branch.
     - Assuming you configured an automatic trigger in your Jenkins Master (see [Jenkins sub-module README](../0-bootstrap/modules/jenkins-agent)), this will trigger a plan. You can also trigger a Jenkins job manually. Given the many options to do this in Jenkins, it is out of the scope of this document see [Jenkins website](http://www.jenkins.io) for more details.
    ```
    git push --set-upstream origin plan

2-environments/README.md

@@ -103,24 +103,29 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
    git add .
    git commit -m 'Your message'
    ```
-1. Push your plan branch to trigger a plan for all environments.
+1. Push your plan branch to trigger a plan for all environments. Because the
+   _plan_ branch is not a [named environment branch](./docs/FAQ.md), pushing your _plan_
+   branch triggers _terraform plan_ but not _terraform apply_.
    ```
    git push --set-upstream origin plan
    ```
 1. Review the plan output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to development.
+1. Merge changes to development branch. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b development
    git push origin development
    ```
 1. Review the apply output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to non-production.
+1. Merge changes to non-production. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b non-production
    git push origin non-production
    ```
 1. Review the apply output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to production branch.
+1. Merge changes to production branch. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b production
    git push origin production

3-networks/README.md

@@ -155,26 +155,31 @@ If you are not able to use Dedicated or Partner Interconnect, you can also use a
     1. Run `terraform plan` and review output.
     1. Run `terraform apply`.
     1. If you would like the bucket to be replaced by Cloud Build at run time, change the bucket name back to `UPDATE_ME`.
-1. Push your plan branch to trigger a plan.
+1. Push your plan branch to trigger a plan for all environments. Because the
+   _plan_ branch is not a [named environment branch](./docs/FAQ.md), pushing your _plan_
+   branch triggers _terraform plan_ but not _terraform apply_.
    ```
    git push --set-upstream origin plan
    ```
 1. Review the plan output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to production.
+1. Merge changes to production. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b production
    git push origin production
    ```
 1. Review the apply output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. After production has been applied, apply development.
-1. Merge changes to development.
+1. Merge changes to development. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b development
    git push origin development
    ```
 1. Review the apply output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. After development has been applied, apply non-production.
-1. Merge changes to non-production.
+1. Merge changes to non-production. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b non-production
    git push origin non-production

4-projects/README.md

@@ -159,26 +159,31 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
    git add .
    git commit -m 'Your message'
    ```
-1. Push your plan branch to trigger a plan.
+1. Push your plan branch to trigger a plan for all environments. Because the
+   _plan_ branch is not a [named environment branch](./docs/FAQ.md), pushing your _plan_
+   branch triggers _terraform plan_ but not _terraform apply_.
    ```
    git push --set-upstream origin plan
    ```
 1. Review the plan output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to production.
+1. Merge changes to production. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b production
    git push origin production
    ```
 1. Review the apply output in your Cloud Build project. https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. After production has been applied, apply development.
-1. Merge changes to development.
+1. Merge changes to development. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b development
    git push origin development
    ```
 1. Review the apply output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. After development has been applied, apply non-production.
-1. Merge changes to non-production.
+1. Merge changes to non-production. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b non-production
    git push origin non-production

5-app-infra/README.md

@@ -149,24 +149,29 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
    git add .
    git commit -m 'Your message'
    ```
-1. Push your plan branch to trigger a plan for all environments.
+1. Push your plan branch to trigger a plan for all environments. Because the
+   _plan_ branch is not a [named environment branch](./docs/FAQ.md), pushing your _plan_
+   branch triggers _terraform plan_ but not _terraform apply_.
    ```
    git push --set-upstream origin plan
    ```
  1. Review the plan output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_INFRA_PIPELINE_PROJECT_ID
-1. Merge changes to development.
+1. Merge changes to development. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b development
    git push origin development
    ```
 1. Review the apply output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_INFRA_PIPELINE_PROJECT_ID
-1. Merge changes to non-production.
+1. Merge changes to non-production. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+   pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b non-production
    git push origin non-production
    ```
 1. Review the apply output in your Cloud Build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_INFRA_PIPELINE_PROJECT_ID
-1. Merge changes to production branch
+1. Merge changes to production branch. Because this is a [named environment branch](./docs/FAQ.md#what-is-a-named-branch),
+      pushing to this branch triggers both _terraform plan_ and _terraform apply_.
    ```
    git checkout -b production
    git push origin production

docs/FAQ.md

@@ -10,3 +10,20 @@ We recommend that your request 50 additional projects for the service account, `
 You can use the [Request Project Quota Increase](https://support.google.com/code/contact/project_quota_increase) form to request the quota increase.
 In the support form, for **Email addresses that will be used to create projects**, use the `terraform_service_account` address that's created in the organization bootstrap module.
 If you see other quota errors, see the [Quota documentation](https://cloud.google.com/docs/quota).
+
+## What is a "named" branch?
+
+Certain branches in the terraform-example-foundation are considered to be
+_named branches_. Pushing to a named branch causes the _apply_ command to be
+run. Pushing to branches other than the named branches does not run _apply_.
+
+* development
+* non-production
+* production
+
+## Which Terraform commands are run when I push to a branch?
+
+If you pushed to a _named branch_ the following commands are run: _init_, _plan_, _validate_, _apply_.
+
+If you push to a branch that is not a named branch, only _init_, _plan_, and
+_validate_ are run. The _apply_ command is not run.