FAQ

Quick answers to common questions about adopting and using the DevOps Engineering Style Guide.

Getting Started¶

How do I get started with this style guide?¶

Start with the Getting Started guide, which walks through setup, prerequisites, and first steps. If you prefer a hands-on approach, try the Zero to Validated Python Project tutorial.

Which languages does this style guide cover?¶

The guide covers 19+ languages and tools across infrastructure, programming, CI/CD, and configuration:

Infrastructure as Code: Terraform, Terragrunt, HCL, AWS CDK, CloudFormation, Bicep, Pulumi, Kubernetes/Helm, Crossplane, GitOps
Configuration Management: Ansible
Programming: Python, Go, TypeScript, Bash, PowerShell, SQL
CI/CD: GitHub Actions, GitLab CI, Jenkins/Groovy
Data Formats: YAML, JSON, JSON Schema, TOML/INI
Containers: Dockerfile, Docker Compose, Dev Containers
Build Tools: Makefile, Task, Just

See the full Language Comparison Matrix for feature-by-feature comparisons.

How do I choose the right tool for my project?¶

Use the Decision Trees to walk through common scenarios and get tool recommendations based on your requirements.

How do I adopt this guide incrementally?¶

The Maturity Model defines five levels of adoption, from basic formatting to full AI-optimized compliance. Start at Level 1 and progress as your team matures.

Validation and Linting¶

How do I validate my code against this style guide?¶

There are three approaches, from simplest to most comprehensive:

1. Pre-commit hooks (recommended for all projects):

# Install pre-commit hooks
pre-commit install

# Run all hooks manually
pre-commit run --all-files

2. Container-based validation (no local dependencies needed):

docker run --rm -v $(pwd):/workspace \
  ghcr.io/tydukes/coding-style-guide:latest validate

3. Local scripts (for this repository):

uv run python scripts/validate_metadata.py docs/
uv run python scripts/analyze_code_ratio.py
bash scripts/pre_commit_linter.sh

See the Local Validation Setup guide for detailed instructions.

How do I set up pre-commit hooks?¶

Follow the Pre-commit Hooks Guide or use the Pre-commit Config Template as a starting point for your project.

How do I integrate validation into my CI/CD pipeline?¶

GitHub Actions: See the GitHub Actions Guide and Workflow Templates
GitLab CI: See the GitLab CI Guide
Jenkins: See the Jenkins Pipeline Guide

Why does the spell checker fail on my new technical terms?¶

The spell checker uses a whitelist of allowed terms in .github/cspell.json. Add new technical terms to the words array in that file. Run locally first to verify:

npx cspell "docs/**/*.md"

Language-Specific Questions¶

How do I validate Python code?¶

Python validation uses Black (formatting) and Flake8 (linting):

# Format with Black
uv run black .

# Lint with Flake8
uv run flake8

# Type checking with mypy
uv run mypy .

See the Python Style Guide for complete standards.

What's the difference between Terraform and Terragrunt?¶

Terraform is the IaC tool that defines infrastructure resources using HCL. Terragrunt is a thin wrapper around Terraform that helps keep configurations DRY, manages remote state, and orchestrates dependencies between modules.

Use Terraform for module definitions: Terraform Guide
Use Terragrunt for live infrastructure orchestration: Terragrunt Guide
See also the HCL Guide for the underlying configuration language

How should I format my Bash scripts?¶

Follow the Bash Style Guide. Key requirements:

Always use #!/usr/bin/env bash shebang
Run ShellCheck on all scripts
Use set -euo pipefail for error handling
Quote all variables: "${var}"

Which CI/CD platform should I use?¶

That depends on your ecosystem:

GitHub-hosted repos: GitHub Actions is the natural choice
GitLab-hosted repos: GitLab CI is tightly integrated
Enterprise/complex pipelines: Jenkins offers maximum flexibility

See the Decision Trees for a guided recommendation.

How do I write Dockerfiles that follow this guide?¶

See the Dockerfile Style Guide and the Dockerfile Template for a ready-to-use starting point. Key principles: multi-stage builds, minimal base images, and non-root users.

Templates and Examples¶

Where do I find project templates?¶

All templates are in the Templates section:

Template	Use Case
README	Project documentation
Terraform Module	IaC modules
Python Package	Python libraries
Dockerfile	Container images
GitHub Actions	CI/CD workflows
Helm Chart	Kubernetes deployments
CONTRACT.md	Module contracts

Are there complete example projects?¶

Yes, see the Examples section for full, production-ready implementations:

Metadata and Documentation¶

What metadata tags should I include in my code?¶

At minimum, include @module, @description, and @version. The full schema is documented in the Metadata Schema Reference.

"""
@module my_module
@description Handles user authentication and session management
@version 1.0.0
@author Tyler Dukes
@last_updated 2025-01-15
@status stable
"""

What's the 3:1 code-to-text ratio?¶

Language guides must maintain at least 3 lines of code examples for every 1 line of explanatory text. This "show, don't tell" philosophy ensures guides are example-rich and practical. Verify with:

uv run python scripts/analyze_code_ratio.py

How do I add YAML frontmatter to documentation files?¶

Every documentation file needs this frontmatter:

---
title: "Document Title"
description: "Brief purpose description"
author: "Tyler Dukes"
tags: [tag1, tag2, tag3]
category: "Category Name"
status: "active"
---

Security¶

How do I set up security scanning?¶

See the Security Scanning Guide for SAST, DAST, dependency scanning, and container scanning setup.

How do I handle secrets in my code?¶

Never commit secrets to version control. Use environment variables or secret management tools. The pre-commit hooks include detect-private-key to catch accidental commits. See the Environment Configuration guide for secret management patterns.

How should I handle dependency updates?¶

Follow the Dependency Update Policies guide. Use Dependabot or Renovate for automated dependency updates, and configure auto-merge for trusted sources.

Testing¶

What testing strategy should I follow?¶

The Testing Strategies guide covers the test pyramid, coverage targets, and when to use each test type. For IaC-specific testing, see IaC Testing Standards.

How do I test infrastructure code?¶

Use the IaC Testing Standards which covers Terratest, Kitchen, InSpec, and OPA. The CONTRACT.md Template provides a framework for defining testable guarantees.

How do I set up performance testing?¶

See the Performance Testing Standards for load testing, benchmarking, and performance budgets.

Migration¶

How do I migrate from PEP 8 to this style guide?¶

See the PEP 8 Migration Guide. The main differences are Black formatting (100-char line length vs PEP 8's 79) and metadata tag requirements.

How do I migrate from the Google Style Guide?¶

See the Google Style Guide Migration for a detailed comparison and step-by-step transition plan.

How do I migrate from the Airbnb Style Guide?¶

See the Airbnb Style Guide Migration for JavaScript/TypeScript-specific migration steps.

Contributing¶

How do I contribute to this style guide?¶

See CONTRIBUTING.md for guidelines. All commits must follow the conventional commit format.

How do I add a new language guide?¶

Follow the Language Guide Template structure. Key requirements:

Create the file in docs/02_language_guides/
Include YAML frontmatter with all required fields
Maintain a 3:1 code-to-text ratio
Update mkdocs.yml navigation
Add search keywords for discoverability

Can't find what you're looking for? Check the Topic Index, Glossary, or use the search bar above. You can also open an issue for additional help.