Skip to content

Contributing

Scope

This repository is infrastructure-only for TenantZero AI.

  • Terraform modules and environment stacks
  • Security and operations docs
  • Validation and CI helper scripts

No app/runtime code should be added here.

Coding Standards

All contributions must follow the infrastructure coding standards documented in CODING_STANDARDS.md. Key requirements:

Module Contracts

  • Every module must define clear input variables with descriptions and types
  • Every module must expose meaningful outputs
  • Modules accept resource_group_name, location, and tags — never assume upstream context
  • Modules must not reference sibling modules or call other modules directly
  • No hidden defaults — every default must be explicit and documented

Composition

  • Root stacks (envs/<env>/) are the composition layer
  • Modules are composed explicitly — avoid conditional module creation inside modules
  • New capabilities extend the stack; they do not modify existing modules

Governance Separation

  • Governance modules (policy, RBAC, diagnostics, alerts) must not be mixed into networking or compute modules
  • Policy assignments, role definitions, and audit logging belong in governance namespace

Identity and Security

  • All services must use managed identity
  • No secret-based application access
  • Key Vault RBAC authorization only
  • No shared keys in the application layer

Observability

  • No module ships without diagnostic wiring
  • Every service must emit diagnostics to Log Analytics
  • Retention policies must be configurable

Workflow

  1. Create a feature branch from main.
  2. Make focused changes with clear commit messages.
  3. Run local checks before opening a pull request.
  4. Open a PR using the repository template.

Local Validation

Run these before requesting review:

./scripts/preflight.sh
./scripts/validate.sh

If Terraform is installed, also run a targeted plan in the affected env:

cd envs/dev
terraform init
terraform plan

Terraform Rules

  • No inline JSON policies — use structured objects.
  • Use locals for computed values, not repeated expressions.
  • Every module must expose outputs.
  • No direct resource references across modules.
  • Avoid implicit provider behavior.
  • Explicit version pinning for providers.
  • Backend configuration must be externalized.

Pull Request Expectations

  • Explain intent, scope, and risk.
  • Call out security-impacting changes.
  • Include example input/output changes when module interfaces are updated.
  • Keep documentation in sync with infrastructure changes.
  • Update DECISIONS.md when making architectural choices.

Commit Guidance

Use imperative, scoped commit messages, for example:

  • Add diagnostics support for private endpoints
  • Harden Key Vault module network defaults

Security Reporting

Do not include secrets in code, examples, issues, or PRs. If a security issue is discovered, notify maintainers privately through your internal channel.