Tools Guidelines

Standards for creating and organizing tools in the /tools directory.

Directory Structure

Tools are organized by functional categories:

• release/ - Release management and automation
• database/ - Database utilities and scripts
• testing/ - Testing automation and utilities
• ci/ - CI/CD helper scripts
• development/ - Development workflow utilities

Naming Conventions

Script Names

• Use kebab-case: generate-test-report.sh
• Start with action verb: generate-, bump-, validate-
• Include context: bump-version.sh, validate-migrations.sh
• Use .sh extension for bash scripts

Directory Names

• Lowercase with hyphens: release/, database/
• Name by function, not implementation

Requirements

Each subdirectory must contain:

• README.md documenting all tools in that category
• Tool descriptions with usage examples
• Prerequisites and dependencies

Script Standards

Self-Documentation

• Required: Implement --help flag with usage, options, and examples
• Scripts should be self-documenting, not require external documentation
• Use standard CLI patterns: -h, --help for help

Technical Standards

• Start with #!/bin/bash
• Use set -euo pipefail
• Source common utilities: source "$(dirname "$0")/../common.sh"
• Make executable (chmod +x)
• Use proper error handling and validation
• Handle unknown arguments gracefully