Contributing¶

Thank you for your interest in contributing to Azure Functions Practical Guide!

Quick Start¶

Fork the repository
Clone: git clone https://github.com/yeongseon/azure-functions-practical-guide.git
Install dependencies: pip install mkdocs-material mkdocs-minify-plugin
Start local preview: mkdocs serve
Open http://127.0.0.1:8000 in your browser
Create a feature branch: git checkout -b feature/your-change
Make changes and validate: mkdocs build --strict
Submit a Pull Request

Repository Structure¶

.
├── .github/
│   └── workflows/              # GitHub Pages deployment
├── apps/
│   ├── python/                 # Python reference application (v2 model)
│   ├── nodejs/                 # Node.js reference application (v4 model)
│   ├── dotnet/                 # .NET reference application (isolated worker)
│   └── java/                   # Java reference application (Maven)
├── docs/
│   ├── assets/                 # Images, icons
│   ├── best-practices/         # Production patterns and anti-patterns
│   ├── javascripts/            # Mermaid zoom JS
│   ├── language-guides/
│   │   ├── python/             # Python — 4 plans tutorials + recipes
│   │   ├── nodejs/             # Node.js — 4 plans tutorials + recipes
│   │   ├── java/               # Java — 4 plans tutorials + recipes
│   │   └── dotnet/             # .NET — 4 plans tutorials + recipes
│   ├── operations/             # Day-2 operational execution
│   ├── platform/               # Architecture and design decisions
│   ├── reference/              # CLI cheatsheet, host.json, limits
│   ├── start-here/             # Overview, learning paths, repository map
│   ├── stylesheets/            # Custom CSS
│   └── troubleshooting/        # Troubleshooting hub
│       ├── architecture.md
│       ├── evidence-map.md
│       ├── first-10-minutes/   # First-10-minutes guides
│       ├── kql/                # KQL query packs
│       ├── lab-guides/         # Lab guide documents
│       ├── methodology/        # Methodology guides
│       └── playbooks/          # Playbook documents
├── infra/                      # Bicep templates for all hosting plans
├── labs/                       # Lab infrastructure + app source
└── mkdocs.yml                  # MkDocs Material configuration

Content Categories¶

Section	Purpose
Start Here	Entry points, learning paths, repository map
Platform	Architecture, design decisions — WHAT and HOW it works
Best Practices	Production patterns — HOW to use the platform well
Language Guides	Per-language step-by-step tutorials and recipes
Operations	Day-2 execution — HOW to run in production
Troubleshooting	Diagnosis and resolution — hypothesis-driven
Reference	Quick lookup — CLI, host.json, platform limits

Document Templates¶

Every document must follow the template for its section. Do not invent new structures.

Platform docs¶

# Title
Brief introduction (1-2 sentences)
## Prerequisites (optional)
## Main Content
### Subsections
## Advanced Topics (optional)
## See Also
## Sources

Best Practices docs¶

# Title
Brief introduction
## Why This Matters
## Recommended Practices
## Common Mistakes / Anti-Patterns
## Validation Checklist
## See Also
## Sources

Operations docs¶

# Title
Brief introduction
## Prerequisites
## When to Use
## Procedure
## Verification
## Rollback / Troubleshooting
## See Also
## Sources

Tutorial docs (Language Guides)¶

# Title
Brief introduction
## Prerequisites
## What You'll Build
## Steps
## Verification
## Next Steps / Clean Up (optional)
## See Also
## Sources (optional)

Playbooks¶

# Title (no intro paragraph)
## 1. Summary
## 2. Common Misreadings
## 3. Competing Hypotheses
## 4. What to Check First
## 5. Evidence to Collect
## 6. Validation and Disproof by Hypothesis
## 7. Likely Root Cause Patterns
## 8. Immediate Mitigations
## 9. Prevention (optional)
## See Also
## Sources (optional)

Lab Guides¶

# Title
Brief introduction
## Lab Metadata (table: difficulty, duration, tier, etc.)
## 1) Background
## 2) Hypothesis
## 3) Runbook
## 4) Experiment Log
## Expected Evidence
## Clean Up
## Related Playbook
## See Also
## Sources

Reference docs¶

# Title
Brief introduction
## Topic/Command Groups
## Usage Notes
## See Also

## See Also

- [Repository Map](../start-here/repository-map.md)
- [Learning Paths](../start-here/learning-paths.md)
## Sources

Writing Standards¶

CLI Commands¶

# ALWAYS use long flags for readability
az functionapp create --resource-group $RG --name $APP_NAME --plan $PLAN_NAME --runtime python

# NEVER use short flags in documentation
az functionapp create -g $RG -n $APP_NAME  # ❌ Don't do this

CLI element	Explanation
Command(s)	`az functionapp create`
Key flags	`--resource-group`, `--name`, `--plan`, `--runtime`
Variables	`$RG`, `$APP_NAME`, `$PLAN_NAME`
Expected result	Azure CLI returns provisioning details; confirm the resource name and successful provisioning state before continuing.

Variables¶

Variable	Description	Example
`$RG`	Resource group name	`rg-functions-demo`
`$APP_NAME`	Function app name	`func-demo-app`
`$PLAN_NAME`	Hosting plan	`plan-demo-functions`
`$STORAGE_NAME`	Storage account	`stdemofunctions`
`$LOCATION`	Azure region	`koreacentral`
`$SUBSCRIPTION_ID`	Subscription identifier placeholder	`<subscription-id>`

Mermaid Diagrams¶

All architectural diagrams use Mermaid. Every documentation page should include at least one diagram.

Nested Lists¶

All nested list items MUST use 4-space indent (Python-Markdown standard).

Admonitions¶

For MkDocs admonitions, indent body content by 4 spaces:

!!! warning "Title"
    Body text here.

Tail Sections¶

Every document ends with these sections in order:

## See Also — internal cross-links within this repository
## Sources — external references (Microsoft Learn URLs)

Content Source Policy¶

All content must be traceable to official Microsoft Learn documentation.

Source Type	Description	Allowed?
`mslearn`	Directly from Microsoft Learn	Required for platform content
`mslearn-adapted`	Adapted from Microsoft Learn	Yes, with source URL
`self-generated`	Original content	Requires justification

PII Rules¶

NEVER include real Azure identifiers in documentation or examples:

Subscription IDs: use <subscription-id>
Tenant IDs: use <tenant-id>
Emails: use user@example.com
Secrets, tokens, connection strings: NEVER include

Build and Validate¶

# Install dependencies
pip install mkdocs-material mkdocs-minify-plugin

# Validate (must pass before submitting PR)
mkdocs build --strict

# Local preview
mkdocs serve

Tutorial Validation Dashboard Scope¶

docs/reference/validation-status.md tracks executable leaf tutorial runbooks under docs/language-guides/*/tutorial/<hosting-plan>/*.md.

The dashboard intentionally excludes:

Tutorial index.md chooser pages, because they explain plan selection and navigation rather than an end-to-end Azure deployment.
Troubleshooting lab guides under docs/troubleshooting/lab-guides/, because they are experiment reports. Validate them through their lab metadata, experiment log, expected evidence, and content source metadata instead of tutorial validation frontmatter.

Only add or update tutorial validation frontmatter after actually executing the documented steps against Azure. Do not add synthetic last_tested dates to close dashboard gaps.

Git Commit Style¶

type: short description

Allowed types: feat, fix, docs, chore, refactor

Review Process¶

Automated CI checks (MkDocs build)
Maintainer review for accuracy and completeness
Merge to main triggers GitHub Pages deployment

Code of Conduct¶

Please read our Code of Conduct before contributing.