From af299cabc4d0376e9643f59a28b9c26bad79e4e8 Mon Sep 17 00:00:00 2001 From: Kristopher Turner Date: Mon, 13 Apr 2026 00:12:10 +0000 Subject: [PATCH] =?UTF-8?q?fix(structure):=20move=20standards/=20into=20do?= =?UTF-8?q?cs/standards/=20=E2=80=94=20all=20docs=20under=20/docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No documentation should live outside /docs in the platform repo. Moving the 11 canonical standards .mdx files into docs/standards/ so they appear in the MkDocs nav and are co-located with the how-to pages about the standards system (consuming, contributing, propagation, authoring-guide). Changes: - Move standards/*.mdx → docs/standards/*.md (rename extension for MkDocs) - Convert Docusaurus :::admonition syntax → MkDocs !!! admonition syntax - Delete root-level standards/ entirely - Add all 11 content files to mkdocs.yml nav under Standards section - Update templates/_common/STANDARDS.md stub URL (docs/standards/) - Update ADR-0002 path references - Update sync workflow in azurelocal.github.io: source path + copies .md as .mdx so Docusaurus site extension stays consistent Closes #6 Co-Authored-By: Claude Sonnet 4.6 --- decisions/0002-standards-single-source.md | 6 +-- .../standards/automation.md | 5 +- .../standards/documentation.md | 0 .../standards/examples.md | 5 +- docs/standards/index.md | 45 +++++++++++++++--- .../standards/infrastructure.md | 0 .../naming.mdx => docs/standards/naming.md | 0 .../standards/new-repo-setup.md | 0 .../standards/repository-management.md | 0 .../standards/scripting.md | 0 .../standards/solutions.md | 10 ++-- .../testing.mdx => docs/standards/testing.md | 10 ++-- .../standards/variables.md | 0 mkdocs.yml | 11 +++++ standards/README.md | 32 ------------- standards/index.mdx | 47 ------------------- templates/_common/STANDARDS.md | 2 +- 17 files changed, 66 insertions(+), 107 deletions(-) rename standards/automation.mdx => docs/standards/automation.md (90%) rename standards/documentation.mdx => docs/standards/documentation.md (100%) rename standards/examples.mdx => docs/standards/examples.md (95%) rename standards/infrastructure.mdx => docs/standards/infrastructure.md (100%) rename standards/naming.mdx => docs/standards/naming.md (100%) rename standards/new-repo-setup.mdx => docs/standards/new-repo-setup.md (100%) rename standards/repository-management.mdx => docs/standards/repository-management.md (100%) rename standards/scripting.mdx => docs/standards/scripting.md (100%) rename standards/solutions.mdx => docs/standards/solutions.md (87%) rename standards/testing.mdx => docs/standards/testing.md (88%) rename standards/variables.mdx => docs/standards/variables.md (100%) delete mode 100644 standards/README.md delete mode 100644 standards/index.mdx diff --git a/decisions/0002-standards-single-source.md b/decisions/0002-standards-single-source.md index bd7afcc..74aa1ae 100644 --- a/decisions/0002-standards-single-source.md +++ b/decisions/0002-standards-single-source.md @@ -17,13 +17,13 @@ We need one authoritative home for standards docs that: ## Decision -Canonical standards docs live **only** in `AzureLocal/platform/standards/`. No other repo keeps a local copy. +Canonical standards docs live **only** in `AzureLocal/platform/docs/standards/`. No other repo keeps a local copy. Distribution model: -1. **Community docs site** (`azurelocal.github.io`) continues to render standards for humans. It pulls `platform/standards/*.mdx` via a scheduled GitHub Actions workflow (scheduled on platform release tags). The site renders, the platform repo authors. +1. **Community docs site** (`azurelocal.github.io`) continues to render standards for humans. It pulls `platform/docs/standards/*.md` via a scheduled GitHub Actions workflow and publishes them as `.mdx` in the site's `standards/` folder. The site renders, the platform repo authors. -2. **Product repos** carry a `STANDARDS.md` stub (~6 lines) at repo root that links to [`https://github.com/AzureLocal/platform/tree/main/standards`](https://github.com/AzureLocal/platform/tree/main/standards). No files copied. +2. **Product repos** carry a `STANDARDS.md` stub (~6 lines) at repo root that links to [`https://github.com/AzureLocal/platform/tree/main/docs/standards`](https://github.com/AzureLocal/platform/tree/main/docs/standards). No files copied. 3. **Maintenance**: standards changes are PRs against `platform`. Typos need no ADR; substantive changes do. diff --git a/standards/automation.mdx b/docs/standards/automation.md similarity index 90% rename from standards/automation.mdx rename to docs/standards/automation.md index 713d6cd..a5945df 100644 --- a/standards/automation.mdx +++ b/docs/standards/automation.md @@ -40,9 +40,8 @@ flowchart TB | **PowerShell** | ✅ | ✅ | ✅ | ✅ | | **Ansible** | ✅ | ✅ | ✅ | ✅ | -:::warning[Delegates] -"Delegates" means the IaC tool provisions Azure resources but does not configure the guest OS or application layer. A separate tool (PowerShell or Ansible) handles guest configuration. -::: +!!! warning "Delegates" + "Delegates" means the IaC tool provisions Azure resources but does not configure the guest OS or application layer. A separate tool (PowerShell or Ansible) handles guest configuration. --- diff --git a/standards/documentation.mdx b/docs/standards/documentation.md similarity index 100% rename from standards/documentation.mdx rename to docs/standards/documentation.md diff --git a/standards/examples.mdx b/docs/standards/examples.md similarity index 95% rename from standards/examples.mdx rename to docs/standards/examples.md index bcf24de..d92e191 100644 --- a/standards/examples.mdx +++ b/docs/standards/examples.md @@ -10,10 +10,9 @@ All examples, sample configurations, and walkthroughs use **one** fictional company: **Infinite Improbability Corp (IIC)**. -:::warning[Mandatory] -Never use `contoso`, `fabrikam`, `adventure-works`, `woodgrove`, `example.com`, or any real customer name. +!!! warning "Mandatory" + Never use `contoso`, `fabrikam`, `adventure-works`, `woodgrove`, `example.com`, or any real customer name. **IIC only** — in every repo, every example, every sample config. -::: --- diff --git a/docs/standards/index.md b/docs/standards/index.md index 432de46..a83b766 100644 --- a/docs/standards/index.md +++ b/docs/standards/index.md @@ -1,13 +1,46 @@ --- -title: Standards -status: stub +title: "Standards" +sidebar_label: "Standards" +sidebar_position: 10 +description: "Standards and conventions" --- # Standards -!!! warning "Stub page" - This page is seeded for navigation. Real content lands in a later phase of the platform rollout. Track progress in the implementation plan. +This repository follows the **org-wide AzureLocal standards** maintained on the central documentation site. -## What belongs on this page +!!! info "Central Standards" + The full standards suite is at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/). + This section provides the key rules adapted for this solution. -TODO — fill in during the appropriate rollout phase. +--- + +## Standards Pages + +| Standard | Local Page | Central Reference | +|----------|-----------|------------------| +| Documentation | [Documentation Standards](documentation) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) | +| Repository Management | [Repository Management Standard](repository-management) | [Full Reference](https://azurelocal.cloud/standards/repository-management/) | +| Scripting | [Scripting Standards](scripting) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) | +| Variables | [Variable Standards](variables) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) | +| Naming Conventions | [Naming Conventions](naming) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) | +| Solutions | [Solution Standards](solutions) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) | +| Infrastructure | [Infrastructure Standards](infrastructure) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) | +| Automation | [Automation Interoperability](automation) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) | +| Examples & IIC | [Examples & IIC](examples) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) | + +--- + +## References + +- [Variable Reference](variables) — Per-variable catalog for this repo +- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout +- [Repository Management Standard](repository-management) — Portfolio-level governance and repo-management contract + +--- + +## Repo-Specific Conventions + +- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible +- **Config contract**: runtime `config/variables/variables.yml`, template `config/variables/variables.example.yml`, schema `config/variables/schema/variables.schema.json`, bootstrap policy defined in [Variable Standards](variables) +- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples) \ No newline at end of file diff --git a/standards/infrastructure.mdx b/docs/standards/infrastructure.md similarity index 100% rename from standards/infrastructure.mdx rename to docs/standards/infrastructure.md diff --git a/standards/naming.mdx b/docs/standards/naming.md similarity index 100% rename from standards/naming.mdx rename to docs/standards/naming.md diff --git a/standards/new-repo-setup.mdx b/docs/standards/new-repo-setup.md similarity index 100% rename from standards/new-repo-setup.mdx rename to docs/standards/new-repo-setup.md diff --git a/standards/repository-management.mdx b/docs/standards/repository-management.md similarity index 100% rename from standards/repository-management.mdx rename to docs/standards/repository-management.md diff --git a/standards/scripting.mdx b/docs/standards/scripting.md similarity index 100% rename from standards/scripting.mdx rename to docs/standards/scripting.md diff --git a/standards/solutions.mdx b/docs/standards/solutions.md similarity index 87% rename from standards/solutions.mdx rename to docs/standards/solutions.md index 9f6bf66..b9f8fb4 100644 --- a/standards/solutions.mdx +++ b/docs/standards/solutions.md @@ -22,9 +22,8 @@ Each solution maps to an infrastructure type in the [master registry](./variable | AI-Assisted Operations | `copilot` | [`azurelocal-copilot`](https://github.com/AzureLocal/azurelocal-copilot) | | Azure Local Ranger | `ranger` | [`azurelocal-ranger`](https://github.com/AzureLocal/azurelocal-ranger) | -:::info[Non-IaC Solutions] -Some solutions (e.g. Ranger, Copilot, Load Testing Tools) are operational or diagnostic tools rather than IaC deployment solutions. They follow the same repository management standards but the IaC tool support, parameter derivation, and multi-tool parity sections below do not apply. Their solution-specific architecture is documented in their own repos. -::: +!!! info "Non-IaC Solutions" + Some solutions (e.g. Ranger, Copilot, Load Testing Tools) are operational or diagnostic tools rather than IaC deployment solutions. They follow the same repository management standards but the IaC tool support, parameter derivation, and multi-tool parity sections below do not apply. Their solution-specific architecture is documented in their own repos. --- @@ -40,9 +39,8 @@ Each tool must declare which deployment phases it supports: | **PowerShell** | ✅ | ✅ | ✅ | ✅ | | **Ansible** | ✅ | ✅ | ✅ | ✅ | -:::warning[Delegates] -"Delegates" means the tool provisions Azure resources but does not configure the guest OS. A separate tool (PowerShell or Ansible) handles guest configuration. -::: +!!! warning "Delegates" + "Delegates" means the tool provisions Azure resources but does not configure the guest OS. A separate tool (PowerShell or Ansible) handles guest configuration. --- diff --git a/standards/testing.mdx b/docs/standards/testing.md similarity index 88% rename from standards/testing.mdx rename to docs/standards/testing.md index 0fd0141..9f3efa0 100644 --- a/standards/testing.mdx +++ b/docs/standards/testing.md @@ -13,9 +13,8 @@ description: "MAPROOM fixtures, TRAILHEAD scenarios, and IIC canon — how Azure Testing in AzureLocal is centralized. The frameworks, schemas, and canonical test data live in [`AzureLocal/platform/testing/`](https://github.com/AzureLocal/platform/tree/main/testing) and are consumed by every product repo. This standard defines **what each repo must test** and **which framework primitives it must use** — it does not re-describe the frameworks themselves (those have their own docs under [`docs/maproom/`](https://github.com/AzureLocal/platform/tree/main/docs/maproom) and [`docs/trailhead/`](https://github.com/AzureLocal/platform/tree/main/docs/trailhead) once Phase 2 ships). -:::info[Phase status] -Phase 1 (this document) establishes the **standard**. Phase 2 ships the **framework** (`AzureLocal.Maproom` PowerShell module, fixture + IIC schemas, TRAILHEAD harness). Until Phase 2 lands, repos continue to reference [`azurelocal-S2DCartographer/tests/maproom/`](https://github.com/AzureLocal/azurelocal-S2DCartographer/tree/main/tests/maproom) as the interim canonical implementation. -::: +!!! info "Phase status" + Phase 1 (this document) establishes the **standard**. Phase 2 ships the **framework** (`AzureLocal.Maproom` PowerShell module, fixture + IIC schemas, TRAILHEAD harness). Until Phase 2 lands, repos continue to reference [`azurelocal-S2DCartographer/tests/maproom/`](https://github.com/AzureLocal/azurelocal-S2DCartographer/tree/main/tests/maproom) as the interim canonical implementation. --- @@ -31,9 +30,8 @@ Every test in an AzureLocal repo falls into exactly one of these classes. The cl | **scenario** (TRAILHEAD) | Scripted end-to-end walkthrough with pass/fail gates. User-journey shaped: "user does X, expects Y". | `tests/trailhead/` | TRAILHEAD harness (Phase 2) | | **drift-audit** | Assert a live environment still matches its MAPROOM fixture after time passes. Runs scheduled, not per-commit. | `tests/drift/` | `AzureLocal.Maproom` + scheduled workflow | -:::warning[Classification under review] -The five-class taxonomy above is the **current** rule. An open platform issue ([#3](https://github.com/AzureLocal/platform/issues/3)) is reviewing whether additional classes (compliance assertion, synthetic load, migration-inventory differ, repo conformance) should become first-class. Until that issue closes, treat anything outside the five classes as repo-local tooling — do not lift it into `platform/testing/` without ADR approval. -::: +!!! warning "Classification under review" + The five-class taxonomy above is the **current** rule. An open platform issue ([#3](https://github.com/AzureLocal/platform/issues/3)) is reviewing whether additional classes (compliance assertion, synthetic load, migration-inventory differ, repo conformance) should become first-class. Until that issue closes, treat anything outside the five classes as repo-local tooling — do not lift it into `platform/testing/` without ADR approval. --- diff --git a/standards/variables.mdx b/docs/standards/variables.md similarity index 100% rename from standards/variables.mdx rename to docs/standards/variables.md diff --git a/mkdocs.yml b/mkdocs.yml index ce79920..8f6e735 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -122,6 +122,17 @@ nav: - Rollback: onboarding/rollback.md - Standards: - standards/index.md + - Automation: standards/automation.md + - Documentation: standards/documentation.md + - Examples & IIC: standards/examples.md + - Infrastructure: standards/infrastructure.md + - Naming: standards/naming.md + - New repo setup: standards/new-repo-setup.md + - Repository management: standards/repository-management.md + - Scripting: standards/scripting.md + - Solutions: standards/solutions.md + - Testing: standards/testing.md + - Variables: standards/variables.md - Consuming: standards/consuming.md - Contributing: standards/contributing.md - Propagation: standards/propagation.md diff --git a/standards/README.md b/standards/README.md deleted file mode 100644 index e86f49e..0000000 --- a/standards/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Standards - -**Single source of truth for AzureLocal organization standards.** - -These documents were previously duplicated across 7+ repos. In Phase 1 of the platform rollout, all local copies were deleted and replaced with a [`STANDARDS.md`](../templates/_common/STANDARDS.md) stub that points here. - -The docs site at [`AzureLocal.github.io/azurelocal.github.io/standards`](https://azurelocal.github.io/azurelocal.github.io/standards) continues to render these for humans — it pulls from this folder via a scheduled sync workflow. - -## Files - -| File | Scope | -|---|---| -| `index.mdx` | Entry point — table of contents | -| `automation.mdx` | Automation conventions (PowerShell, Ansible, Azure CLI, Bicep helpers) | -| `documentation.mdx` | How to write and structure docs across the org | -| `examples.mdx` | Fictional company / IIC canon rules for sample data | -| `infrastructure.mdx` | IaC conventions (Bicep, Terraform, ARM) | -| `naming.mdx` | Repo, branch, tag, variable, resource naming | -| `new-repo-setup.mdx` | Process for creating a new AzureLocal repo | -| `repository-management.mdx` | Per-repo structure, CODEOWNERS, branch protection | -| `scripting.mdx` | PowerShell authoring conventions | -| `solutions.mdx` | How solution repos are organized | -| `variables.mdx` | Canonical variable registry | -| `testing.mdx` | MAPROOM / TRAILHEAD / IIC testing conventions | - -## Editing - -Changes to any standards doc require an ADR in [`../decisions/`](../decisions) (except typo fixes). See [`docs/standards/contributing.md`](../docs/standards/contributing.md) for the PR workflow. - -## Consuming from a product repo - -See [`docs/standards/consuming.md`](../docs/standards/consuming.md). TL;DR: put a `STANDARDS.md` stub at your repo root linking to this folder — do not copy the files locally. diff --git a/standards/index.mdx b/standards/index.mdx deleted file mode 100644 index 26073c1..0000000 --- a/standards/index.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Standards" -sidebar_label: "Standards" -sidebar_position: 10 -description: "Standards and conventions" ---- - -# Standards - -This repository follows the **org-wide AzureLocal standards** maintained on the central documentation site. - -:::info[Central Standards] -The full standards suite is at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/). - This section provides the key rules adapted for this solution. -::: - ---- - -## Standards Pages - -| Standard | Local Page | Central Reference | -|----------|-----------|------------------| -| Documentation | [Documentation Standards](documentation) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) | -| Repository Management | [Repository Management Standard](repository-management) | [Full Reference](https://azurelocal.cloud/standards/repository-management/) | -| Scripting | [Scripting Standards](scripting) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) | -| Variables | [Variable Standards](variables) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) | -| Naming Conventions | [Naming Conventions](naming) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) | -| Solutions | [Solution Standards](solutions) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) | -| Infrastructure | [Infrastructure Standards](infrastructure) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) | -| Automation | [Automation Interoperability](automation) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) | -| Examples & IIC | [Examples & IIC](examples) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) | - ---- - -## References - -- [Variable Reference](variables) — Per-variable catalog for this repo -- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout -- [Repository Management Standard](repository-management) — Portfolio-level governance and repo-management contract - ---- - -## Repo-Specific Conventions - -- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible -- **Config contract**: runtime `config/variables/variables.yml`, template `config/variables/variables.example.yml`, schema `config/variables/schema/variables.schema.json`, bootstrap policy defined in [Variable Standards](variables) -- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples) \ No newline at end of file diff --git a/templates/_common/STANDARDS.md b/templates/_common/STANDARDS.md index a782ed2..81506ad 100644 --- a/templates/_common/STANDARDS.md +++ b/templates/_common/STANDARDS.md @@ -2,7 +2,7 @@ AzureLocal organization standards are maintained centrally in the [`AzureLocal/platform`](https://github.com/AzureLocal/platform) repository. This repo does **not** keep a local copy. -- **Canonical source**: [`AzureLocal/platform/standards/`](https://github.com/AzureLocal/platform/tree/main/standards) +- **Canonical source**: [`AzureLocal/platform/docs/standards/`](https://github.com/AzureLocal/platform/tree/main/docs/standards) - **Rendered for humans**: [azurelocal.cloud/standards](https://azurelocal.cloud/standards/) - **Governance**: [ADR-0002 — Standards as single source of truth](https://github.com/AzureLocal/platform/blob/main/decisions/0002-standards-single-source.md)