Skip to content

v0.4.0 Lab 7 Contribution

Jump to bottom
CARMLPipelinePrincipal edited this page Oct 25, 2022 · 1 revision

In this lab, you will learn how a contribution to the source repository (in this example the CARML main repository) would look like. At a customer, the same approach could be used to allow teams to contribute to a central library.

NOTE: The contribution described in this lab may already be implemented in CARML. However, my just slightly modifying the given examples (e.g. add another word) the lab will work as intended.

Navigation

Step 1 - Create a contribution branch

For the subsequent contribution, you first need a new branch. Similar to the other labs, create one by performing the following sequence of steps:

  1. In VSCode, change the branch to main and fetch the latest changes. You can achieve this in two ways:

    Alternative 1: Via VSCode's terminal

    1. If Terminal is not in sight, you can alternatively open it by expanding the Terminal-dropdown on the top, and selecting New Terminal

    2. Executing the following commands

          git checkout 'main'
    git pull
    Alternative 2: Via VSCode's UI

    1. Initiate the branch change by selecting the current branch on the bottom left of the VSCode window

      Change branch

    2. Next, a dropdown opens where you select the main branch

      Select main

    3. Finally, you only have to trigger the Sychronize symbol on the bottom left next to the active branch

      Sync main

  1. Next, create a new branch contribution. You can achieve this in two ways:

    Alternative 1: Via VSCode's terminal

    1. If a Terminal is not in sight, you can alternatively open it by expanding the Terminal-dropdown on the top, and selecting New Terminal

    2. Now, execute the following PowerShell commands:

      git checkout -b 'contribution'
git push --set-upstream 'origin' 'contribution'
    Alternative 2: Via VSCode's UI

    1. Select the current branch on the bottom left of VSCode

      Change branch main

    2. Select + Create new branch in the opening dropdown

      Init create branch

    3. Enter the new branch name contribution

      Enter name

    4. Push the new branch to your GitHub fork by selecting Publish Branch to the left in the 'Source Control' tab

      Git push

Step 2 - Implement the contribution

The first step of any contribution is its implementation. For the sake if this lab, we will suggest a simple contribution that will allow you the make use of some of our tools:

  1. In your local VSCode, navigate via modules, on to Microsoft.Network and finally to the routeTable's template deploy.bicep

    Availability Set VSCode

  2. A simple contribution to perform is to define an additional output. The Bicep template will return its value upon successful execution. As you will notice in a later lab, these outputs are particularly useful when multiple modules are orchestrated together. Please add the following snippet to the end of the file:

    @description('The routes of the deployed route table.')
output route array = routeTable.properties.routes

  3. As adding an output is a feature update, we also have to update the version.json file, incrementing the minor version number by 1.

Step 3 - Run local test(s)

CARML comes with a number of tools that you can use to perform several automated tasks for you. One of these tools can be use to perform the same tests locally as you would see in the pipeline. To do so, please perform the following tasks:

  1. Navigate through the folders utilities and tools and click on the script Test-ModuleLocally.ps1.

    Open Test Local script

  2. Next, you must load the function implemented in the script by triggering the Run button to the top right of VSCode.

    load script for testing

    Note: Should VSCode ask you (in the terminal) whether you are sure you want to execute the script, please confirm Enable execution

  3. Once confirmed, the function will be loaded and can be invoked via the command of the same name Test-ModuleLocally. As stated earlier, the script replicates the feeling of the pipeline. That means, it can run a simple Pester test, but also a deployment which includes a parameter file using tokens. For our purpose, please invoke the function as follows

    $TestModuleLocallyInput = @{
    templateFilePath           = '<PathToTheUpdatedTemplate>' # Get the path via a right-click on the updated template file in VSCode & select 'Copy Path'
    PesterTest                 = $true
}
Test-ModuleLocally @TestModuleLocallyInput -Verbose

  4. Confirm to execute the script. After a moment, the terminal will show the test cases that are executed and should show one failed test

    Failed test

    So why did it fail? Well, as per its description: The ReadMe outputs section should document all outputs defined in the template file. Before, you added a new template output, but the readme remained in its original state.

Step 4 - Re-generate the documentation

To update the readme, we provide another utility called Set-ModuleReadMe. This script again takes the template file path as an input an creates / updates almost all content of the module's readme file for you.

  1. To get started you need to load the function first. Like before, load the script in path utilities\tools\Set-ModuleReadMe.ps1.

    load script for readme

  2. Next, you can invoke the function as follows

    Set-ModuleReadMe -TemplateFilePath '<PathToTheUpdatedTemplate>' # Get the path via a right-click on the updated template file in VSCode & select 'Copy Path'

  3. Once you confirmed the execution of the script you should notice that the module's readme.md file is marked as modified.

    ReadMe Updated Log

  4. If you open version control to the left you should notice at least the template file deploy.bicep and readme file readme.md to be marked as changed. If you click on the readme specifically, a comparison view will open and show you that the readme was correctly updated

    ReadMe Updated

Step 5 - Re-Run local test(s)

With the readme updated we can now re-run the test to confirm everything is in order.

  1. Select again the terminal and either use your arrow-up key go through your previous commands until the get to the one that triggered the test (Test-ModuleLocally), or copy the same snipped from Step 2.

    $TestModuleLocallyInput = @{
    templateFilePath           = '<PathToTheUpdatedTemplate>' # Get the path via a right-click on the updated template file in VSCode & select 'Copy Path'
    PesterTest                 = $true
}
Test-ModuleLocally @TestModuleLocallyInput -Verbose

  2. This time, however, none of the tests should fail:

    Test succeeded

Step 6 - Upload your changes and run the module pipeline

Now that the contribution is implemented and the tests are green, you can continue to prepare everything for the subsequent pull request.

  1. The first thing you have to do is to upload your changes. You can do this either via the terminal or by using the Git integration of VSCode:

    Alternative 1: Via VSCode's terminal

    1. If a Terminal is not in sight, you can alternatively open it by expanding the Terminal-dropdown on the top, and selecting New Terminal

    2. Now, execute the following PowerShell commands:

      git add .
git commit -m 'Added output to route table'
git push
    Alternative 2: Via VSCode's UI

    1. Add your changes: If not already there, navigate to the source control menu to the left and add the changed files to the commit. To do so, select the + icon next to Changes (appears when hovering)

      Open source control

    2. Commit your changes: Next, you should give the commit a meaningful message such as 'Added output to route table' and can then click the checkmark symbol on the top to create the commit

      Git commit

    3. Push your changes: Finally, you can push the changes to the repository by selecting the blue Publish Branch button

      Git push

  2. Back in your fork, navigate to Actions

    Open actions

  3. From the list of actions to the left, select Network: RouteTables followed by the Run workflow dropdown to the right

    Select actions

  4. Further select your branch from the Branch: dropdown

    Select branch

  5. And finally trigger the pipeline with the default settings by selecting Run workflow

    Trigger run

    Subsequently, the pipeline will start running through the the same tests you executed locally, but also execute the simulated deployment, followed by an actual test deployment in Azure.

  6. While the pipeline is running, we can use the time to create a Pull Request. However, before doing so, you can take the chance to create a pipeline badge that you can attach to the later Pull Request. This badge will show the reviewer that the code changes were successfully validated & tested. To create a badge, first select the three dots (...) to the top right of the pipeline, and further the Create status badge option.

    Badge dropdown

  7. In the opening pop up, you first need to select your branch and then click on the Copy status badge Markdown

    Status badge

Step 7 - Create a Pull Request

In this step you will create the pull request. Do do so, perform the following tasks:

  1. Navigate to Pull requests tab on the top. Here you should have multiple options:

    • As you just uploaded changes to a branch, there is an automated popup that allows you to create a pull request for that branch directly
    • Alternatively, you can create a blank pull request via the New pull request button.

    Select now the New pull request button.

    Pull request init

  2. This opens a new view in the Azure/ResourceModules (target) repository. Here,

    • make sure your branch is selected on the top right
    • you provide a meaningful title
    • you provide a meaningful description. This description should include the pipeline badge you copied at the end of from Step 5
    • select the correct type of change. In this case it would be a New feature
    Pull request raw

  3. Once you entered all the details, you can open a preview of the final look by selecting Preview on the top and finally select Create pull request to the bottom right.

Step 8 - Exclude environment-specific changes

Part of your pull request are 1 (or more) files that should not be pushed into the target repository, as they contain details specific to your environment:

  • settings.yml

To undo these changes you can use any of the following 2 alternatives:

Alternative 1: Via VSCode's terminal

To reset these files back to original state, run the following command to connect your local repo to the upstream repo and restoring all but the routeTables files:

  1. Connect to the upstream repo and restore all but the routeTable files from it.
    git remote add upstream https://github.com/Azure/ResourceModules.git
    git fetch upstream
    git restore --source upstream/main * ':!*routeTables*'

  1. See that the files are restored in "Source Control" in VSCode, and adjust if necessary. I.e. remove any of the "restored" changes you want to bring in.

  2. Commit all files and push to your branch. This will update the PR too.

    git commit -a -m 'Reset settings files'
    git push
Alternative 2: Via VSCode's UI
  1. In your Visual Studio Code, open the settings.yml file in the root directory
Settings YAML fork
  1. Now, open the settings.yml of the CARML repository, copy its content and overwrite it in your local file in VSCode
Settings YAML CARML
  1. Once done, perform the same actions of Step 6 to upload your changes to the branch. These changes will automatically be available in the Pull Request you created earlier.

If ready, proceed to the next lab: Lab 8 - Build an ACR driven solution

This wiki is being actively developed

Wiki content

Clone this wiki locally