From 0c71b72f7fe02ac7c5ea272d5df250b992d2ce63 Mon Sep 17 00:00:00 2001 From: Brendan Kowitz Date: Fri, 17 Oct 2025 15:34:51 -0700 Subject: [PATCH] Adds critical build flag --- build/ci-pipeline.yml | 40 ++++++++++--- build/jobs/docker-build-all.yml | 31 +++++----- build/pr-pipeline.yml | 40 ++++++++++--- docs/arch/adr-2510-critical-build-flag.md | 70 +++++++++++++++++++++++ 4 files changed, 152 insertions(+), 29 deletions(-) create mode 100644 docs/arch/adr-2510-critical-build-flag.md diff --git a/build/ci-pipeline.yml b/build/ci-pipeline.yml index 3957890576..e226790e1e 100644 --- a/build/ci-pipeline.yml +++ b/build/ci-pipeline.yml @@ -1,12 +1,20 @@ -# DESCRIPTION: -# Builds, tests, and packages the solution for the main branch. +# DESCRIPTION: +# Builds, tests, and packages the solution for the main branch. name: $(SourceBranchName)-$(Date:yyyyMMdd)$(Rev:-r) trigger: none +parameters: +- name: buildCriticalOnly + displayName: 'Build Critical Versions Only (skip R4B/R5)' + type: boolean + default: false + variables: - template: ci-variables.yml - template: build-variables.yml +- name: buildCriticalOnly + value: ${{ parameters.buildCriticalOnly }} stages: # *********************** Setup *********************** @@ -124,7 +132,7 @@ stages: steps: - template: ./jobs/analyze.yml -- stage: DockerBuild +- stage: DockerBuild displayName: 'Build images' dependsOn: - UpdateVersion @@ -132,9 +140,10 @@ stages: assemblySemFileVer: $[stageDependencies.UpdateVersion.Semver.outputs['SetVariablesFromGitVersion.assemblySemFileVer']] jobs: - template: ./jobs/docker-build-all.yml - parameters: + parameters: tag: $(ImageTag) buildPlatform: $(publicDockerImagePlatforms) + buildCriticalOnly: ${{ parameters.buildCriticalOnly }} # *********************** Stu3 *********************** - stage: redeployStu3 @@ -217,11 +226,12 @@ stages: # *********************** R4B *********************** - stage: redeployR4B displayName: 'Redeploy R4B CosmosDB Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild jobs: - template: ./jobs/redeploy-webapp.yml - parameters: + parameters: version: R4B webAppName: $(DeploymentEnvironmentNameR4B) subscription: $(ConnectedServiceName) @@ -229,11 +239,12 @@ stages: - stage: redeployR4BSql displayName: 'Redeploy R4B SQL Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild jobs: - template: ./jobs/redeploy-webapp.yml - parameters: + parameters: version: R4B webAppName: $(DeploymentEnvironmentNameR4BSql) subscription: $(ConnectedServiceName) @@ -241,6 +252,7 @@ stages: - stage: testR4B displayName: 'Run R4B Tests' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - BuildArtifacts - redeployR4B @@ -256,11 +268,12 @@ stages: # *********************** R5 *********************** - stage: redeployR5 displayName: 'Redeploy R5 CosmosDB Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild jobs: - template: ./jobs/redeploy-webapp.yml - parameters: + parameters: version: R5 webAppName: $(DeploymentEnvironmentNameR5) subscription: $(ConnectedServiceName) @@ -268,11 +281,12 @@ stages: - stage: redeployR5Sql displayName: 'Redeploy R5 SQL Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild jobs: - template: ./jobs/redeploy-webapp.yml - parameters: + parameters: version: R5 webAppName: $(DeploymentEnvironmentNameR5Sql) subscription: $(ConnectedServiceName) @@ -280,6 +294,7 @@ stages: - stage: testR5 displayName: 'Run R5 Tests' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - BuildArtifacts - redeployR5 @@ -295,6 +310,15 @@ stages: # *********************** Finalize *********************** - stage: DockerAddTag displayName: 'Docker add main tag' + # Run only if all required tests succeed (all 4 when buildCriticalOnly=false, only Stu3/R4 when buildCriticalOnly=true) + condition: | + and( + succeeded(), + or( + and(eq(variables.buildCriticalOnly, false), succeeded('testStu3'), succeeded('testR4'), succeeded('testR4B'), succeeded('testR5')), + and(eq(variables.buildCriticalOnly, true), succeeded('testStu3'), succeeded('testR4')) + ) + ) dependsOn: - testStu3 - testR4 diff --git a/build/jobs/docker-build-all.yml b/build/jobs/docker-build-all.yml index a44df9750e..a0fd70379d 100644 --- a/build/jobs/docker-build-all.yml +++ b/build/jobs/docker-build-all.yml @@ -1,4 +1,4 @@ -# DESCRIPTION: +# DESCRIPTION: # Builds and pushes images for all supported FHIR versions parameters: @@ -6,28 +6,33 @@ parameters: type: string - name: buildPlatform type: string +- name: buildCriticalOnly + type: boolean + default: false jobs: - template: docker-build-push.yml - parameters: + parameters: version: "R4" tag: ${{parameters.tag}} buildPlatform: ${{parameters.buildPlatform}} -- template: docker-build-push.yml - parameters: - version: "R4B" - tag: ${{parameters.tag}} - buildPlatform: ${{parameters.buildPlatform}} +- ${{ if eq(parameters.buildCriticalOnly, false) }}: + - template: docker-build-push.yml + parameters: + version: "R4B" + tag: ${{parameters.tag}} + buildPlatform: ${{parameters.buildPlatform}} - template: docker-build-push.yml - parameters: + parameters: version: "Stu3" tag: ${{parameters.tag}} buildPlatform: ${{parameters.buildPlatform}} -- template: docker-build-push.yml - parameters: - version: "R5" - tag: ${{parameters.tag}} - buildPlatform: ${{parameters.buildPlatform}} \ No newline at end of file +- ${{ if eq(parameters.buildCriticalOnly, false) }}: + - template: docker-build-push.yml + parameters: + version: "R5" + tag: ${{parameters.tag}} + buildPlatform: ${{parameters.buildPlatform}} \ No newline at end of file diff --git a/build/pr-pipeline.yml b/build/pr-pipeline.yml index fe3058945a..6befb2cb5c 100644 --- a/build/pr-pipeline.yml +++ b/build/pr-pipeline.yml @@ -1,11 +1,19 @@ -# DESCRIPTION: -# Builds, tests, and packages the solution for all PR requests. +# DESCRIPTION: +# Builds, tests, and packages the solution for all PR requests. trigger: none +parameters: +- name: buildCriticalOnly + displayName: 'Build Critical Versions Only (skip R4B/R5)' + type: boolean + default: false + variables: - template: pr-variables.yml - template: build-variables.yml +- name: buildCriticalOnly + value: ${{ parameters.buildCriticalOnly }} stages: - stage: UpdateVersion @@ -95,7 +103,7 @@ stages: steps: - template: ./jobs/analyze.yml -- stage: DockerBuild +- stage: DockerBuild displayName: 'Build images' dependsOn: - UpdateVersion @@ -103,9 +111,10 @@ stages: assemblySemFileVer: $[stageDependencies.UpdateVersion.Semver.outputs['SetVariablesFromGitVersion.assemblySemFileVer']] jobs: - template: ./jobs/docker-build-all.yml - parameters: + parameters: tag: $(ImageTag) buildPlatform: $(testDockerImagePlatforms) + buildCriticalOnly: ${{ parameters.buildCriticalOnly }} - stage: provisionEnvironment displayName: Provision Environment @@ -271,13 +280,14 @@ stages: - stage: deployR4B displayName: 'Deploy R4B CosmosDB Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild - setupEnvironment - createNsp jobs: - template: ./jobs/provision-deploy.yml - parameters: + parameters: version: R4B webAppName: $(DeploymentEnvironmentNameR4B) appServicePlanName: '$(appServicePlanName)-cosmos' @@ -290,13 +300,14 @@ stages: - stage: deployR4BSql displayName: 'Deploy R4B SQL Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild - setupEnvironment - deploySqlServer jobs: - template: ./jobs/provision-deploy.yml - parameters: + parameters: version: R4B sql: true webAppName: $(DeploymentEnvironmentNameR4BSql) @@ -313,13 +324,14 @@ stages: - stage: deployR5 displayName: 'Deploy R5 CosmosDB Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild - setupEnvironment - createNsp jobs: - template: ./jobs/provision-deploy.yml - parameters: + parameters: version: R5 webAppName: $(DeploymentEnvironmentNameR5) appServicePlanName: '$(appServicePlanName)-cosmos' @@ -332,13 +344,14 @@ stages: - stage: deployR5Sql displayName: 'Deploy R5 SQL Site' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - DockerBuild - setupEnvironment - deploySqlServer jobs: - template: ./jobs/provision-deploy.yml - parameters: + parameters: version: R5 sql: true webAppName: $(DeploymentEnvironmentNameR5Sql) @@ -385,6 +398,7 @@ stages: - stage: testR4B displayName: 'Run R4B Tests' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - BuildArtifacts - setupEnvironment @@ -400,6 +414,7 @@ stages: - stage: testR5 displayName: 'Run R5 Tests' + condition: eq(variables.buildCriticalOnly, false) dependsOn: - BuildArtifacts - setupEnvironment @@ -415,6 +430,15 @@ stages: - stage: cleanup displayName: 'Cleanup Azure Environment' + # Run only if all required tests succeed (all 4 when buildCriticalOnly=false, only Stu3/R4 when buildCriticalOnly=true) + condition: | + and( + succeeded(), + or( + and(eq(variables.buildCriticalOnly, false), eq(dependencies.testStu3.result, 'Succeeded'), eq(dependencies.testR4.result, 'Succeeded'), eq(dependencies.testR4B.result, 'Succeeded'), eq(dependencies.testR5.result, 'Succeeded')), + and(eq(variables.buildCriticalOnly, true), eq(dependencies.testStu3.result, 'Succeeded'), eq(dependencies.testR4.result, 'Succeeded')) + ) + ) dependsOn: - testStu3 - testR4 diff --git a/docs/arch/adr-2510-critical-build-flag.md b/docs/arch/adr-2510-critical-build-flag.md new file mode 100644 index 0000000000..626edd0230 --- /dev/null +++ b/docs/arch/adr-2510-critical-build-flag.md @@ -0,0 +1,70 @@ +# ADR 2510: Critical-Only Build Flag for CI/PR Pipelines +Labels: [CI/CD](https://github.com/microsoft/fhir-server/labels/Area-CI-CD) + +## Context +The FHIR server supports four FHIR specification versions: STU3, R4, R4B, and R5. In production environments, the majority of deployments use STU3 and R4, which are mature and widely adopted specifications. R4B and R5 are newer versions with limited production usage. + +The current CI and PR pipelines build, deploy, and test all four versions for every commit. Each version requires: +- Docker image builds (multi-platform for CI) +- Deployment to test environments (CosmosDB + SQL variants) +- Integration tests (CosmosDB + SQL) +- End-to-end tests (CosmosDB + SQL) + +This comprehensive validation is essential for ensuring quality across all supported versions. However, when shipping critical hotfixes or iterating rapidly on production issues affecting only R4 or STU3, the time spent deploying and testing R4B and R5 represents significant overhead. A typical full CI build takes substantial time, with R4B and R5 stages accounting for approximately 40% of deployment and test time. + +We need a mechanism to accelerate builds when working exclusively on R4 and STU3 production issues, while maintaining the default behavior of comprehensive multi-version validation. + +## Decision +We will add a `buildCriticalOnly` parameter to both the CI and PR pipeline definitions. When set to `true`, this parameter will: + +1. **Skip deployment and test stages** for R4B and R5 versions: + - Deployment stages (CosmosDB + SQL) + - Integration test jobs + - End-to-end test jobs + +2. **Skip Docker image builds** for R4B and R5 versions in the `docker-build-all.yml` job template + +3. **Continue to build all code** in the solution, including R4B and R5 projects, during the build stages. This ensures that changes to shared code (e.g., Core libraries) do not introduce compilation errors in non-critical versions. + +The parameter will default to `false`, ensuring that the standard behavior remains comprehensive validation across all versions. Developers and release engineers can opt into the fast path explicitly when appropriate. + +### Implementation Approach +- Add `buildCriticalOnly` parameter (type: boolean, default: false) to pipeline definitions +- Use Azure Pipelines conditional syntax (`condition: eq(variables.buildCriticalOnly, false)`) on R4B and R5 stages +- Update stage dependencies to handle conditionally skipped stages +- Use template conditionals (`${{ if }}`) to skip R4B/R5 Docker builds + +### Usage Guidelines +**When to use `buildCriticalOnly: true`:** +- Hotfixes for production R4 or STU3 issues +- Rapid iteration during R4/STU3 feature development +- Cost-sensitive CI runs when R4B/R5 validation is not required + +**When NOT to use it:** +- Before merging to main branch (full validation recommended) +- When changes affect shared Core libraries (cross-version validation needed) +- Release builds +- When explicitly developing or fixing R4B/R5 functionality + +## Status +Accepted + +## Consequences +### Benefits: +- **Reduced build time**: 20-30% time savings by skipping ~40% of deployment and test stages +- **Faster hotfix delivery**: Critical R4/STU3 fixes can be validated and shipped more quickly +- **Lower build costs**: Reduced Azure DevOps agent minutes and Azure resource usage for test environments +- **Preserved safety**: Default behavior remains unchanged; full validation is opt-out, not opt-in + +### Adverse Effects: +- **Maintenance overhead**: New parameter must be propagated when adding future FHIR versions +- **Risk of misuse**: Developers might use the flag inappropriately, skipping validation when it's needed +- **Incomplete time savings**: All code still compiles, so savings are less than a full solution filter approach would provide + +### Neutral Effects: +- **No impact on default behavior**: Existing builds and processes remain unchanged + +## References +- CI Pipeline: `build/ci-pipeline.yml` +- PR Pipeline: `build/pr-pipeline.yml` +- Docker Build Template: `build/jobs/docker-build-all.yml`