Skip to content

Create standards replication mechanism from docs site to all repos #6

@kristopherjturner

Description

@kristopherjturner

Problem

The Azure Local org has standards documentation that lives in two places:

  1. Primary: azurelocal.github.io (Docusaurus site at azurelocal.cloud) — the canonical source
  2. Local copies: Each repo (e.g., azurelocal-sofs-fslogix/docs/standards/ with 8 files, azurelocal-avd referencing the site) has its own standards docs

Both repos need to be standalone (they're separate repos, separate teams may contribute), so having local standards is valid. But there's no mechanism to keep them in sync — manual copy leads to drift.

Proposal

Create an automated mechanism to replicate standards changes from the primary source (azurelocal.github.io) to all subscriber repos.

Option A: GitHub Action — Standards Sync Bot

A scheduled GitHub Action in azurelocal.github.io that:

  1. Detects changes to standards docs on push to main
  2. Opens a PR in each subscriber repo with the updated standards files
  3. Subscriber repos review and merge (or auto-merge if configured)

Option B: Git Submodule / Subtree

Each repo includes the standards directory as a git submodule or subtree pointing to the docs site.

  • Submodule: Cleaner separation, explicit version pinning
  • Subtree: No .gitmodules complexity, but harder to update

Option C: NPM/Package Registry

Publish standards as a versioned package; each repo pins a version in their config.

Option D: Symlink via CI

CI pipeline downloads latest standards from the docs site and injects them during build/deploy.

Acceptance Criteria

  • Choose a replication mechanism (A, B, C, D, or hybrid)
  • Implement the mechanism
  • Test with a standards change flowing from docs site → subscriber repos
  • Document the mechanism in the toolkit or docs site
  • Identify which repos subscribe to standards replication
  • Ensure local repo customizations (if any) aren't overwritten

Affected Repos

  • Source: azurelocal.github.io — primary standards
  • Subscribers: azurelocal-avd, azurelocal-sofs-fslogix, azurelocal-loadtools, azurelocal-vm-conversion-toolkit, azurelocal-toolkit

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions