Skip to content

fix(structure): move standards/ into docs/standards/ — all docs under /docs #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kristopherjturner merged 1 commit into from
Apr 13, 2026
Merged

fix(structure): move standards/ into docs/standards/ — all docs under /docs #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions decisions/0002-standards-single-source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +20 to +26
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that the canonical standards location is platform/docs/standards, there are still in-repo docs that link to the old platform/standards path (e.g. docs/getting-started/why-platform-exists.md, docs/getting-started/glossary.md, docs/onboarding/adopt-from-existing-repo.md). Please update those references to avoid leaving stale links after this ADR change.

Copilot uses AI. Check for mistakes.

3. **Maintenance**: standards changes are PRs against `platform`. Typos need no ADR; substantive changes do.

Expand Down
5 changes: 2 additions & 3 deletions standards/automation.mdx → docs/standards/automation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,8 @@
| **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.

---

Expand All @@ -67,3 +66,3 @@
- [Scripting Standards](scripting)
- [Infrastructure Standards](infrastructure)
- [Solution Standards](solutions)
Expand Down
0 standards/documentation.mdx → docs/standards/documentation.md
View file
Open in desktop
File renamed without changes.
5 changes: 2 additions & 3 deletions standards/examples.mdx → docs/standards/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::

---

Expand Down Expand Up @@ -101,3 +100,3 @@

- **PR review**: Reviewers flag any use of `contoso`, `fabrikam`, or other non-IIC names
- **Config validation**: `variables.example.yml` uses IIC naming in all placeholders
Expand Down
45 changes: 39 additions & 6 deletions docs/standards/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

Check failure on line 46 in docs/standards/index.md

View workflow job for this annotation

GitHub Actions / Markdown lint

Files should end with a single newline character 

docs/standards/index.md:46:87 MD047/single-trailing-newline Files should end with a single newline character https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md047.md
0 standards/infrastructure.mdx → docs/standards/infrastructure.md
View file
Open in desktop
File renamed without changes.
0 standards/naming.mdx → docs/standards/naming.md
View file
Open in desktop
File renamed without changes.
0 standards/new-repo-setup.mdx → docs/standards/new-repo-setup.md
View file
Open in desktop
File renamed without changes.
0 standards/repository-management.mdx → docs/standards/repository-management.md
View file
Open in desktop
File renamed without changes.
0 standards/scripting.mdx → docs/standards/scripting.md
View file
Open in desktop
File renamed without changes.
10 changes: 4 additions & 6 deletions standards/solutions.mdx → docs/standards/solutions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand All @@ -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.

---

Expand Down
10 changes: 4 additions & 6 deletions standards/testing.mdx → docs/standards/testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand All @@ -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.

---

Expand Down
0 standards/variables.mdx → docs/standards/variables.md
View file
Open in desktop
File renamed without changes.
11 changes: 11 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
32 changes: 0 additions & 32 deletions standards/README.md
View file
Open in desktop

This file was deleted.

47 changes: 0 additions & 47 deletions standards/index.mdx
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion templates/_common/STANDARDS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Loading