Adding CI to a BHoM Repository

Introduction

This page provides a brief introduction to how to set up a BHoM repository to include Continuous Integration (CI) checks.

There are some key terms to note for the use of this workflow.

• Check - an action (or collection of) that culminates in a definable operation that is checked against for code validation
• Pipeline - this is the document that outlines the steps a 'check' will undertake
• Bot - this is the automated system providing the CI check

Activating CI checks

Setting up the Repository

1. Make sure you have an issue raised on your repository outlining the desire to initiate CI checks for transparency and follow the usual BHoM guidelines on development (branch naming, PR process, etc.) during this process
2. Clone Test_Toolkit on master branch to get the latest, approved set of CI files required
3. Copy the folder .ci (found within Test_Toolkit/.ci) to your toolkit so that it matches the folder pattern Your_Toolkit/.ci
4. Open each .yml file within a text editor of your choice and alter the following variables:
   • solution - Update this to be the name of your .sln file
   • projectName - Update this to be the name of your repository/folder/project
   • This needs to be done on:
     • check-all-dependants.yml
     • check-core.yml - this should only be copied for Core BHoM repositories and not every toolkit should need this
     • check-installer.yml
     • run-compliance-tests.yml
5. Open testSettings.runsettings file within a text editor of your choice and alter the following variables (near the bottom of the file):
   • projectName - Update this to be the name of your project, same as the one used in item 5 above
   • oMName - Update this to be the name of your oM files, null if you do not have an oM in your toolkit
   • engineName - Update this to be the name of your engine files, null if you do not have an engine in your toolkit
   • adapterName - Update this to be the name of your adapter files, null if you do not have an adapter in your toolkit
6. Ensure the file CloneTest.ps1 exists in Your_Toolkit/.ci/CloneTest.ps1 - but do not make any changes to this file
7. Set up your dependencies.txt file by adding all of the repositories which your repository is dependant on to build, in the format of Organisation/Repository. For example, every toolkit should have BHoM/BHoM and BHoM/BHoM_Engine listed in their dependencies.txt
8. Set up your dependants.txt file by adding all of the repositories which depend on your repository - this should not need to be used by most toolkits, but can be used to check downstream repositories when changes are made to yours
9. Commit these changes against the issue raised and raise a PR on your toolkit
10. Contact the administrators in charge of your given CI platform to initiate pipelines against the repository you have set up CI checks on to begin the next step

Setting up the CI - Azure DevOps

This guidance is specific to the Azure DevOps CI workflow - for alternative workflows you may need to investigate yourself. Please feel free to append additional workflows to this wiki as appropriate.

This process should be repeated for every pipeline you wish to add

1. Go to the Pipelines/Builds part of the Azure panel
2. Create a new folder with the name of your repository to house your pipelines
3. Click to add a new build pipeline
4. Select your code repository (most likely GitHub - not the Enterprise Server)
5. Select your repository from the list
6. Select Existing Azure Pipelines YAML file on the Configure page
7. Select the branch which stores your new .ci files
8. Select the path to the .yml file for this pipeline
9. Click continue
10. Click run to run your pipeline for the first time
11. After your pipeline has run, rename your pipeline to refer to the check being run (e.g. Your_Toolkit.CheckInstaller for the installer pipeline, etc.) - this name should make sense for the pipeline being run

Setting up pipeline triggers

Some pipelines will want to be triggered on different actions than commits. To do this, follow the steps below.

1. Click Edit on the pipeline you wish to set up different triggers on
2. Go to the triggers section
3. Select the triggers for Pull Request Validation as appropriate
4. Click save and give a comment stating what you've done

Done

CI checks are now set up on your repository!