Guidelines

Naming conventions

• Use consistent environment suffixes such as dev, uat, and prod.
• Keep storage-account names lowercase, compact, and compatible with Azure naming restrictions.
• Use snake_case for Python files and variables.
• Use camelCase for Bicep parameters and UPPER_SNAKE_CASE for environment variables.

Configuration and code standards

• Use Python 3.11+ features, including modern type-hint syntax.
• Prefer explicit imports and stable dependency pins.
• Use Ruff for linting and formatting.
• Make operational scripts and deployment steps idempotent and suitable for reruns.
• Catch specific exceptions and log enough context to debug pipeline failures.
• Group parameters by required, optional, then tags.
• Output important identifiers needed by downstream steps.
• Keep resource templates modular and reusable.
• Prefer parameter overrides to editing shared templates for environment-specific values.
• Keep stage and task names explicit.
• Use strict shell error handling in bash steps.
• Validate before pushing, not only after the pipeline fails.
• Treat RBAC, Key Vault recovery, and storage access as first-class deployment concerns.

Documentation guidelines

• Use the platform switch only where behavior actually differs.
• Keep shared guidance outside platform blocks.
• Write operational instructions as runbooks, not marketing copy.
• Prefer concrete repository paths and workflows over generic platform advice.
• Keep client-facing pages focused on how to configure and operate the platform, not on internal framework maintenance.

Change checklist

1. Confirm the change belongs in the data contract, the example implementation, or the shared platform.
2. Validate the affected notebooks, infrastructure, or deployment flow before pushing.
3. Check whether docs and examples still match the repository structure.
4. Keep naming, identity, storage, and validation rules consistent with these docs.