Skip to content

Standards propagation

How a change to a standards document in AzureLocal/platform reaches the ~28 consumer repos.

Standards propagate by reference, not by replication. Consumer repos carry a one-file breadcrumb (STANDARDS.md) that links back to platform. When a platform standard changes, every consumer sees it immediately — no sync job runs, no PR is opened on any consumer.

This is deliberate. Before platform existed, 7 repos had copies of the same /standards/ folder — all drifted. The vendoring approach failed. The current model can't drift by construction.

The propagation surfaces

Surface How it updates
Consumer repo STANDARDS.md Static — one PR at adoption time, never again unless links change
azurelocal.github.io/standards/ site Scheduled sync from platform/standards/ (hourly or daily)
Platform docs site (azurelocal.github.io/platform/) Built from platform/docs/ on every main merge
.azurelocal-platform.yml self-descriptor Consumer updates it when their adopts list changes, not on every standards change

What propagates instantly

  • Linked URL content — consumers follow STANDARDS.md → platform/docs/standards/<topic>.md. The moment platform's main updates, the next click on that link shows the new content.
  • Enforcement rules baked into platform-owned tooling — e.g., a new markdownlint rule in platform's .markdownlint.json affects every consumer that runs reusable-mkdocs-deploy.yml.

What needs a consumer-side action

  • Content-level compliance — if the standard changes what consumers must write, consumers must edit their own files. Drift-check detects file presence, not content conformance.
  • New required files — if the canonical 5 required files becomes 6, every consumer needs a PR.
  • Template structure — new repos pick up template changes automatically; existing repos don't re-scaffold. A separate Sync-CommonFiles.ps1 run propagates _common file changes via PRs.

How Sync-CommonFiles.ps1 helps

When a _common file changes (e.g., CODEOWNERS, .editorconfig, .gitignore), platform can fan out PRs to every consumer:

./repo-management/org-scripts/Sync-CommonFiles.ps1 -DryRun    # see planned changes
./repo-management/org-scripts/Sync-CommonFiles.ps1 -CreatePR  # open PRs on each consumer

This is not automatic — a maintainer runs it. The PRs are named platform/sync-common-files-YYYYMMDD per repo.

When a standards change is enforceable

An enforceable standard is one that CI can check. Examples:

  • "All workflows must set explicit permissions at the job level" — check: grep for permissions: in every .github/workflows/*.yml.
  • "Every repo must have CHANGELOG.md" — check: Test-RepoConformance already does this.

For enforceable standards, platform ships the enforcement alongside the rule:

  • Update the relevant reusable workflow / Test-RepoConformance rule / _common template.
  • Consumers see the failure on their next CI run (or next weekly drift-check.yml).

Non-enforceable standards rely on convention and review.

Detection of content drift

Content-level drift (consumer wrote something that violates a standard) is not detected by platform tooling. It surfaces in code review or incident post-mortems. Automate detection when the cost of manual review exceeds the cost of writing the check.

Timing

Change When consumers see it
Docs-only clarification Immediately — URL-followed content changes
New enforcement in reusable workflow Next CI run (within 24h for repos with daily activity)
_common file change via Sync-CommonFiles.ps1 When the sync PRs merge (manually triggered)
New required file in canonical list After each consumer lands their adoption PR (manually triggered)
IIC canon content change On consumer's next test run — canon is frozen, so this is rare

Communication checklist

When merging a non-trivial standards change:

  • ADR merged alongside
  • CHANGELOG.md entry generated by release-please
  • Note in release notes for consumers to skim
  • If enforceable: confirm the enforcement landed in the same release
  • If it invalidates existing consumer content: file an issue on each affected consumer (or at least the platform repo) with a migration note