Azure Practical Guide Series Contract¶

This file preserves the series-wide structure and navigation contract shared by the Azure Practical Guide repositories. Repository-specific evidence, claim, experiment, and agent rules remain in AGENTS.md at the repository root.

Series-Wide Documentation Contract¶

This repository is part of the Azure Practical Guide series. All repositories in the series must preserve a consistent reader experience while allowing repository-specific extensions.

Core Sections¶

Every service-focused repository SHOULD use these core sections unless the repository-specific addendum explains an exception.

Approved Extension Sections¶

Do not create a new top-level section if the content can fit under one of the core or approved extension sections.

App Service-Specific Addendum¶

This repository is an advanced App Service runtime guide. It uses these approved App Service extension sections in addition to the series core sections.

App Service-Specific Extension Sections¶

App Service Lab Contract Reconciliation¶

The Series Lab Contract v1 applies to App Service reproduction labs as Variant A; Variant B design labs are not used in this repository. Its MUST tier (purpose, testable claim, procedure, evidence method, closing validation and cleanup) applies to each lab document. A labs/<name>/ companion directory, hypothesis and falsification language and a paired playbook are Variant A SHOULD elements, not requirements. The contract does not prescribe a deployment shape or a storage model.

The 15 current scenario directories are recorded in labs/golden-classification.json; labs/_shared is shared infrastructure and is not a scenario. That classification (golden, migration-needed, archive-candidate) records the Golden migration shape. It is not Series Lab Contract conformance, certification, current validation or independent reproduction, and retained evidence trust remains a separate axis.

App Service concerns that its labs address locally, without being series requirements:

Issue and pull-request work uses the local operating format in CONTRIBUTING.md and the canonical priority:critical, priority:high, priority:medium and priority:low definitions in .github/priority-labels.json, as established by

217. All remaining App Service adoption work is closeable in this repository;¶

sibling migrations and architecture-wide coordination are references only.

Repository Structure¶

.
├── .github/
│   └── workflows/              # GitHub Pages deployment
├── apps/
│   ├── python-flask/            # Flask + Gunicorn implementation
│   ├── nodejs/                  # Express.js implementation
│   ├── java-springboot/         # Spring Boot implementation
│   └── dotnet-aspnetcore/       # ASP.NET Core implementation
├── docs/
│   ├── assets/                  # Images, icons
│   ├── best-practices/          # Production patterns
│   ├── language-guides/         # Per-language tutorials
│   ├── operations/              # Day-2 operational tasks
│   ├── platform/                # Architecture and concepts
│   ├── reference/               # CLI cheatsheet, platform limits
│   ├── start-here/              # Entry points
│   └── troubleshooting/         # Playbooks, lab guides, KQL
│       ├── playbooks/           # Detailed failure scenario guides
│       ├── lab-guides/          # Step-by-step issue reproduction
│       └── kql/                 # KQL snippets for diagnostics
├── infra/                       # Bicep/Terraform templates
├── labs/                        # Lab infrastructure and scripts
└── mkdocs.yml                   # MkDocs Material configuration

Start Here Rules¶

Start Here is orientation content. It must not become a language tutorial, SDK tutorial, operations runbook, troubleshooting playbook, or lab guide.

Required pages:

Optional pages:

learning-paths.md MUST:

• Start with role-based or goal-based paths.
• Link to tutorials instead of embedding a full tutorial sequence.
• Avoid service-specific code walkthroughs except short examples.
• Avoid content_validation unless this repository explicitly includes Start Here pages in content validation scope.

Preferred title:

# Learning Paths

Avoid:

# Tutorial: {Service} for {Language}

Navigation Budget¶

The left navigation should help orientation, not expose every file.

Recommended:

• Top-level sections SHOULD stay between 6 and 9 items.
• Direct children under a top-level section SHOULD stay between 5 and 8 items.
• Large collections such as tutorials, recipes, KQL packs, lab guides, and playbooks SHOULD be listed on index pages rather than fully expanded in mkdocs.yml.
• Use hub pages, tables, tags, and search for deep inventory.
• Keep mkdocs.yml readable enough that a contributor can understand the site structure without scrolling through hundreds of deep links.

Preferred troubleshooting structure:

Troubleshooting
├─ Overview
├─ Quick Diagnosis
├─ Decision Tree
├─ First 10 Minutes
├─ Playbooks
├─ KQL Query Packs
└─ Labs

Avoid exposing every individual playbook, KQL query, and lab guide in mkdocs.yml unless the repository is intentionally small.

Related Projects¶

Content Categories¶

The documentation is organized by intent and lifecycle stage:

See Also¶

• Repository Taxonomy
• Golden Evidence Model
• Golden Migration Specification

Sources¶

• Azure Practical Guide series repositories