Follow-up: update context regarding pull request and branching; improve language (#392)

* update context regarding pull request and branching; improve language

* remove unnecessary test file

* fix typo

Co-authored-by: Dexter Williams <Dexterw@microsoft.com>

devops/providers/azure-devops/templates/app_service_maven/README.md

@@ -10,7 +10,7 @@ These YAML templates are designed to handle the build and deploy steps for Maven
 
 ## What is the Shared Maven Service Pipeline?
 
-In order to further simplify **CI/CD** configurations for a **Maven Service**, common CI/CD operations have been abstracted away into a build `yaml` file and release `yaml` file. These two files orchestrate the **Shared Maven Service Pipeline**. The pipeline executes the CI/CD workflow for one or many Maven Services by exposing input parameters that services can use to pass context. The shared pipeline then passes values to other `yaml` files. The pipeline's ability to pass values from one `yaml` file to another is achieved by taking advantage of the [Azure Devops `yaml` templating feature](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema%2Cparameter-schema). In this implementation, the Shared Maven Service Pipeline is hosted in the Cobalt repo but the clients that it serves should each live in their own respective repos. In conclusion, the Shared Maven Service Pipeline holds enough intelligence to service Maven Services even if their project directory structures differ.
+In order to further simplify **CI/CD** configurations for a **Maven Service**, common CI/CD operations have been abstracted away into a build `yaml` file and release `yaml` file. These two files orchestrate the **Shared Maven Service Pipeline**. The pipeline executes the CI/CD workflow for one or many Maven Services by exposing input parameters that services can use to pass context. The shared pipeline then passes values to other `yaml` files. The pipeline's ability to pass values from one `yaml` file to another is achieved by taking advantage of the [Azure Devops `yaml` templating feature](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema%2Cparameter-schema). In this implementation, the Shared Maven Service Pipeline is hosted in the Cobalt repo but each client application that it serves should live in their own respective repos.
 
 - ### Shared Maven Service Pipeline
 
@@ -44,9 +44,11 @@ In order to further simplify **CI/CD** configurations for a **Maven Service**, c
         | App Service CL Update | `app-service-update-commandline.yml` | Updates the App Service startup command with information about the newly deployed JAR file. |
         | Integration Tests | `app-service-deployment-steps.yml` | Automatically detects and runs integration tests using maven tasks. |
 
+    >  The pull request and branching strategy in the diagram above is possible by configuring the PR and Trigger blocks highlighted in the [maven function app usage example](./examples/maven_function_app_usageexample.yml).
+
 - ### Variable group naming conventions
 
-    Variable group naming conventions should be respected. They are hardcoded in the following `yaml` files. It's not recommended to change variable group names.
+    Variable groups are named in a way that allows the pipeline to infer rather or not the group belongs to a specific environment within the release stage. Variable group naming conventions should be respected. They are hardcoded and parameterized in the following `yaml` files and are required. More details about the values of these variable groups are described in the [Maven Service Deployments](./examples/service_usage.md) usage documentation.
 
     | Variable Group | YAML FILE |
     | ---      | ---         |
@@ -56,10 +58,12 @@ In order to further simplify **CI/CD** configurations for a **Maven Service**, c
     |  `${{ provider.name }} Target Env Secrets - ${{ environment }}` | deploy-stages.yml |
     |  `${{ provider.name }} Service Release - ${{ parameters.serviceName }}` | deploy-stages.yml |
 
-- ### Cloud provider boundaries
+- ### Cloud provider and Environment boundaries
 
     The **Shared Maven Service Pipeline** currently accomodates a multi-cloud **Maven Service** deployment. However, current implementation is Azure bound. Azure bound means that if you have a multi-cloud Maven Service, this pipeline only has an execution workflow targeting Azure infrastructure. The service contracts for other cloud providers are in place but have not been implemented.  In short, deployments to a cloud provider are bound by their `yaml` pipeline configuration, the variable groups that belong to them and whether or not the Maven Service solution includes that cloud provider's implementation.
 
+    When adding a new environment for the release stage, satisfy the `${{ environment }}` parameter in the above variable groups. If implementation details have been introduced for other cloud providers, the `${{ provider.name }}` parameters should be used.
+
 ## Next Steps
 
 You may want to try using the **Shared Maven Service Pipeline** to deploy a Maven based java application of your own to the Azure cloud by following the [Maven Service Deployments](./examples/service_usage.md) usage document!

devops/providers/azure-devops/templates/app_service_maven/examples/maven_service_usage_example.yml

@@ -1,3 +1,25 @@
+trigger:
+  batch: true
+  branches:
+    include:
+      - master
+  paths:
+    exclude:
+      - /**/*.md
+      - .gitignore
+
+pr:
+  autoCancel: false
+  branches:
+    include:
+      - '*'
+    exclude:
+      - master
+  paths:
+    exclude:
+      - /**/*.md
+      - .gitignore
+
 variables:
   - group: 'Azure Common Secrets'
   - group: 'Azure - Common'

devops/providers/azure-devops/templates/app_service_maven/examples/service_usage.md

@@ -4,9 +4,27 @@ This document describes how to deploy a **Maven Service** to Azure in Azure Devo
 
 ### Prerequisites
 
-- Cobalt Infrastructure Template for your infrastructure use case has been deployed to Azure.
+- A running App Service deployed from a Cobalt Infrastructure Template.
+- A **Maven Service**
 
-### Step 1: Configure the devops pipelines
+### Step 1: Prepare project structure
+
+Ensure project files (i.e. `settings.xml`, `*.jar`, `pom.xml`, ) can be found relative to the service pipeline `yaml` file. The devops pipelines will need to be configured to consume file paths in the next step.
+
+    ```bash
+    $ tree myjavacontainerapp/provider/javahelloworld-azure
+    ├───pom.xml
+    ├───devops/entry_point.yml
+    └───maven
+    │    ├───settings.xml
+    |    └───...
+    └───javahelloworld-test-azure
+          └───pom.xml
+              ├───...
+              └───..
+    ```
+
+### Step 2: Configure the devops pipelines
 
 The starting point of a **Maven Service** deployment will live in the application code repository. This starting point passes values to the **Shared Maven Service Pipeline**. The Shared Maven Service Pipeline will need to be configured in Azure DevOps. The instructions to do this can be found [here](https://docs.microsoft.com/en-us/azure/devops/pipelines/get-started/pipelines-get-started?view=azure-devops#define-pipelines-using-yaml-syntax). Here is what the starting point of a **Maven Service** pipeline might look like:
 
@@ -72,7 +90,7 @@ Services will typically leverage the following common templates to configure the
   - `testingRootFolder`: Use this parameter to pass the path to your service's integration tests.
   - `mavenPomFile`: 'Use this parameter to pass the path to your pom file.
 
-### Step 2: Configure the Azure DevOps Variable Groups
+### Step 3: Configure the Azure DevOps Variable Groups
 
 Variable groups are named in a way that allows the **Shared Maven Service Pipeline** to look up rather or not the group belongs to a specific cloud provider and for which environment should the group be used for. The following tables describe the variable group names required to support a service deployment. The value columns provide concrete examples for how one might satisfy the variables in each group.
 
@@ -140,6 +158,6 @@ Variable groups are named in a way that allows the **Shared Maven Service Pipeli
   | `MAVEN_INTEGRATION_TEST_POM_FILE_PATH` | ex `drop/deploy/testing/javahelloworld-test-azure/pom.xml` | Path to `pom.xml` that runs integration tests | no | ADO |
   | `SERVICE_RESOURCE_NAME` | ex `$(AZURE_HELLOWORLD_SERVICE_NAME)` | Name of service | no | ADO |
 
-### Step 3: Deploy the Services
+### Step 4: Deploy the Services
 
 The final step in the process is to execute a service deployment pipeline for each **Maven Service**.

devops/providers/azure-devops/templates/function_app_maven/README.md

@@ -32,6 +32,9 @@ In order to simplify **CI/CD** configurations for a **Containerized Java Functio
         | [ACR Push](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/deploy/azure-cli?view=azure-devops)| `acr-push.yml` | Pushes a tar file as an image with an environment tag to an Azure Container Registry. |
         | [Deploy Container Image](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/deploy/azure-cli?view=azure-devops) | `function-deploy.yml` | Deploys ACR image to an Azure Function app |
 
+    
+    > The pull request and branching strategy in the diagram above is possible by configuring the PR and Trigger blocks highlighted in the [maven function app usage example](./examples/maven_function_app_usage_example.yml).
+
 - ### Variable group naming conventions
 
     Variable groups are named in a way that allows the pipeline to infer rather or not the group belongs to a specific environment within the release stage. Variable group naming conventions should be respected. They are hardcoded in the following `yaml` files and are required. More details about the values of these variable groups are described in the [app usage](./examples/function_app_usage.md) example.
@@ -44,3 +47,7 @@ In order to simplify **CI/CD** configurations for a **Containerized Java Functio
 - ### Environment boundaries
 
    The release/cd stage of the **Maven Azure Function Pipeline** cycles through a list of environments provided to it. Environments are properly defined by creating an Azure Devops variable group with the environment naming convention (i.e. `Azure Target Env - ${{ environment }}`). The variable group should hold values needed to for the client application to target a Function App Service currently running from a previous Cobalt Infrastructure Template deployment.
+
+## Next Steps
+
+You may want to try using the **Maven Azure Function Pipeline** to deploy a **Containerized Java Function App** of your own to the Azure cloud by following the [Maven Azure Function Deployment](./examples/function_app_usage.md) usage document!

devops/providers/azure-devops/templates/function_app_maven/examples/maven_function_app_usage_example.yml

@@ -1,3 +1,25 @@
+trigger:
+  batch: true
+  branches:
+    include:
+      - master
+  paths:
+    exclude:
+      - /**/*.md
+      - .gitignore
+
+pr:
+  autoCancel: false
+  branches:
+    include:
+      - '*'
+    exclude:
+      - master
+  paths:
+    exclude:
+      - /**/*.md
+      - .gitignore
+
 variables:
     - group: 'Azure - Common'