A few important factoids to consume about the Repo, before you contribute. There's a lot of info here, to make sure to read it before submitting a PR.
Start by looking through the active issues for low hanging fruit. Another area that will help you get more familiar with the project is by running the Helper Web App locally and writing some new Playwright web tests to make our web publishing/testing process more robust.
Have awareness of the various workflows run on Push / PR / Schedule.
| Workflow | Fires on | Purpose |
|---|---|---|
| Bicep Build | PR | Quality To run the bicep linter upon changes to the bicep files |
| Greetings | Issue / PR | Community Greeting new contributors to the repo |
| Stale bot | Issue / PR | Tidy Marks old issues as stale |
| Labeller | PR | Tidy Adds relevant labels to PR's based on files changed |
| Validate GitHub Pages site | PR | Quality Tests changes to the UI work |
| Release Bicep and Helper | Manual | Publishes a new release and/or new Wizard Web app to GitHub Pages |
| Lighthouse Checks | Schedule | Checks the Wizard Web app for accessibility/seo/performance |
| Check Markdown | PR | Quality Checks markdown files for spelling mistakes |
| Infra CI - Private Cluster | Push / PR / Schedule | Quality Low maturity IaC deployment example. Tests the most secure/private parameter config |
| Infra CI - Byo Vnet Cluster | Push / PR / Schedule | Quality High maturity IaC deployment example. Tests a typical production grade parameter config |
| Infra CI - Starter Cluster | Push / PR / Schedule | Quality Low maturity IaC deployment example. Tests a sandbox grade parameter config |
| InfraCI - Regression Validation | Push / PR / Schedule | Quality Validates multiple parameter files against the bicep code to cover regression scenarios |
| App CI | Manual | Quality Application deployment sample showing different application deployment practices and automation capabilities |
Each has a Validate job, that is required to pass before merging to main. PR's tagged with bug, that contain changes to bicep or workflow files will need to pass all of the jobs in the relevant workflows before merge is possible.
If you're creating a PR from a fork then we're unable to run the typical actions to ensure quality that the core team are able to use. This is because GitHub prevents Forks from leveraging secrets in this repository. PR's from forks will therefore require comprehensive checking from the core team before merging. Don't be surprised if we change the target branch to a new branch in order to properly test the changes before they hit main.
For the most part we try to use feature branches to PR to Main
┌─────────────────┐ ┌───────────────┐
│ │ │ │
│ Feature Branch ├────────►│ Main │
│ │ │ │
└─────────────────┘ └───────────────┘
Branch Policies require the Validation stage of our GitHub Action Workflows to successfully run. The Validation stage does an Az Deployment WhatIf and Validation on an Azure Subscription, however later stages in the Actions that actually deploy resources do not run. This is because we've got a high degree of confidence in the Validate/WhatIf capability. We do run the full stage deploys on a weekly basis to give that warm fuzzy feeling. At some point, we'll run these as part of PR to main.
Where there have been significant changes and we want the full gamut of CI testing to be run on real Azure Infrastructure - then the Develop branch is used. It gives us the nice warm fuzzy feeling before merging into Main. We anticipate the use of the Develop branch is primarily just for use with Forks.
┌─────────────────┐ ┌─────────────┐ ┌────────────┐
│ │ │ │ │ │
│ Feature Branch ├────────►│ Develop ├──────►│ Main │
│ │ │ │ │ │
└─────────────────┘ └─────────────┘ └────────────┘
▲
┌─────────────────┐ │
│ │ │
│ Feature Branch ├───────────────┘
│ │
└─────────────────┘
Releases are used to capture a tested release (all stages, not just Validation), where there are significant new features or bugfixes. The release does not include CI Action files, just the Bicep code.
When changing the Bicep code, try to build into your developer inner loop the following
- Review the linting warnings in VSCode. When you push, the bicep will be compiled to json with warnings/errors picked up
- If creating a new Parameter, choose the least obtrusive default value
- If creating a new Parameter, try to include the corresponding changes to the UI
- If making a breaking change (eg. changing a parameter name or default), pay attention to the Regression parameter files. These will be checked during PR. If the change you're making isn't covered by an existing parameter file, then add one.
- Try to keep naming consistent with the file you're adding to
- Add description decorators liberally
Should be avoided wherever possible, and where necessary highlight the breaking change in the release notes. Version 1.0 will signify a stricter policy around breaking changes.
PSRule for Azure provides analysis for IaC against the Well Architected Framework. It is leveraged in the GitHub actions that run on PR, but you can leverage it locally with the following script;
Install-Module -Name 'PSRule.Rules.Azure' -Repository PSGallery -Scope CurrentUser
$paramPath="./.github/workflows_dep/regressionparams/optimised-for-well-architected.json"
test-path $paramPath
Assert-PSRule -Module 'PSRule.Rules.Azure' -InputPath $paramPath -Format File -outcome ProcessedThe configuration experience is hosted in GitHub pages. It's a static web app, written in NodeJS using FluentUI.
For a deep dive into contributing to the Wizard Web App, please see this document.
Playwright is used to help verify that the app works properly, you can use Playwright in your local dev experience (see Codespaces below), but crucially it's also leveraged as part of the publish process. If the tests don't pass, then the app will not publish. The fragile keyword should be used in any tests where you're learning how they work and run. Once the test is of sufficient quality to be considered a core test, the fragile keyword is removed.
We're trying to ensure that PR's that contain Web UI changes have appropriate Playwright tests that use data-testid for navigating the dom.
A dev container is present in the repo which makes dev and testing of the UI Helper component much easier.
Some helpful terminal commands for when you're getting started with DevContainer/Codespaces experience
Running the Wizard GUI app
cd helper
npm start
#Browser should automatically open. Web app runs on port 3000 on path /AKS-ConstructionRunning the playwright tests after starting the Wizard web app
#Open a new terminal window
cd helper
npx playwright install
npx playwright install-deps chromium
npm i -D playwright-expect
npx playwright test --browser chromium .playwrighttests/ --reporter listIssues that are inactive are marked as stale and then closed pretty aggressively. We'll periodically look through the stale issues to see if any genuine issues have snuck their way through.