Estilo de código

• Os módulos de exemplos e do Terraform devem conter documentação explicando os recursos e como usá-los.

• Todos os links nos arquivos README.md devem ser absolutos para que o site do Terraform Registry os mostre corretamente.

• A documentação pode incluir diagramas criados com mermaid e plantas criadas com o cloudcraft.co.

• Utilize o Terraform pre-commit hooks para garantir que o código seja válido, formatado corretamente e documentado automaticamente antes de ser enviado para o git e revisado por humanos.

Documentação

Documentação gerada automaticamente

O pre-commit é um framework para gerenciar e manter hooks pré-commit multi-idioma. Ele é escrito em Python e é uma ferramente poderosa para fazer algo automaticamente na máquina de um desenvolvedor antes que o código seja enviado para o repositório git. Normalmente, ele é usado para executar linters e formatar código (veja supported hooks).

Com as configurações do Terraform, o pre-commit pode ser usado para formatar e validar o código, bem como para atualizar a documentação.

Confirma o repositório pre-commit-terraform para se familiarizar com ele e os repositórios existentes (por exemplo, terraform-aws-vpc) onde ele já é utilizado.

terraform-docs

O terraform-docs é uma ferramente que faz a geração de documentação a partir de módulos Terraform em vários formatos de saída (output). Você pode executá-lo manualmente (sem ganchos — pre-commit hooks — de pré-commit) ou usar o pre-commit-terraform hooks para atualizar a documentação automaticamente.

@todo: Document module versions, release, GH actions

Recursos

1. pre-commit framework homepage

2. Collection of git hooks for Terraform to be used with pre-commit framework

3. Blog post by Dean Wilson: pre-commit hooks and terraform - a safety net for your repositories