diff --git a/docs/help.md b/docs/help.md new file mode 100644 index 000000000..ad3d74d7d --- /dev/null +++ b/docs/help.md @@ -0,0 +1,150 @@ + +# Guidelines for Printing Usage and Help Information in Atmos + +## Abstract + +This document defines the standards for printing **usage** and **help** information in Atmos CLI. It distinguishes between "usage" and "help," clarifies their purposes, and outlines best practices for implementation. + +--- + +## Definitions + +### Usage + +- **Definition**: A *concise* summary of the correct way to use a specific command or subcommand. It should not show any other helpful information, or examples. +- **Purpose**: + - To provide quick guidance on the syntax and required arguments when a command is misused. + - To assist users in resolving errors without overwhelming them with excessive details. +- **Scope**: + - Usage information is displayed only in error scenarios or upon user request for a brief syntax reminder. + +### Help + +- **Definition**: A detailed explanation of a command or subcommand, including all available options, parameters, and examples. +- **Purpose**: + - To serve as a comprehensive resource for users seeking to understand all features and capabilities of a command. +- **Scope**: + - Help includes usage information but also extends beyond it with detailed documentation. + +--- + +## Usage Guidelines + +1. **When to Display Usage**: + - Display when a command is misused, such as: + - Missing required arguments. + - Invalid arguments provided. + - Syntax errors in the command. + - Example: + + ```plaintext + Error: Missing required argument `--stack`. + Usage: + atmos terraform plan --stack + ``` + +2. **Behavior**: + - **Error Context**: Always display usage after a clear error message. + - **Brevity**: Usage output must be concise and limited to the essential syntax. + - **Exit Code**: Displaying usage must result in a **non-zero exit code**. + - **No Logo**: The usage output must never include the Atmos logo or branding. + +3. **Output Characteristics**: + - Usage must clearly indicate: + - Command syntax. + - Required and optional arguments. + - Minimal explanation to guide correction of misuse. + +--- + +## Help Guidelines + +1. **When to Display Help**: + - Display when the user explicitly requests it, such as: + - Running the `help` subcommand: + + ```bash + atmos help + ``` + + - Using the `--help` flag with a command: + + ```bash + atmos terraform --help + ``` + +2. **Behavior**: + - **Comprehensive**: Help output must include: + - A description of the command. + - All available options, flags, and parameters. + - Examples of usage. + - **Error-Free**: + - Help must always succeed and exit with a **zero exit code**. + - Help should not fail due to misconfigured files, missing dependencies, or validation errors. + - **Static**: + - Help must be non-interactive and preformatted. + +3. **Atmos Logo**: + - The Atmos logo can be included in the `help` output, especially for the main `help` command. + - Subcommands or options help may omit the logo to keep focus on the content. + +4. **No Validation**: + - Help must not perform any validation, such as: + - Checking configuration files. + - Verifying that required tools (e.g., Terraform) are installed. + +5. **Example Output** + + ```plaintext + Atmos CLI - Version 1.0.0 + + Usage: + atmos [options] + + Available Commands: + terraform Manage Terraform workflows + helmfile Manage Helmfile workflows + help Show this help message + + Options: + -v, --version Show the Atmos version + -h, --help Show help for a command + + Examples: + + - Display the current atmos version + + $ atmos version + + - Display the help for the terraform subcommand + + $ atmos terraform --help + + ``` + +--- + +## Comparison of Usage and Help + +| Feature | Usage | Help | +| ----------------------- | --------------------------------------- | ---------------------------------- | +| **Purpose** | Quick syntax guidance after an error | Comprehensive documentation | +| **When Displayed** | After a command misuse or error | Explicitly requested by the user | +| **Content** | Syntax and required arguments only | Detailed descriptions and examples | +| **Exit Code** | Non-zero (when accompanied by an error) | Zero | +| **Includes Logo** | No | Yes | +| **Triggers Validation** | No | No | + +--- + +## Implementation Notes + +1. **Always Return Expected Output**: + - Usage for errors. + - Help for guidance. +2. **Clarity First**: + - Separate error messages from usage or help outputs clearly. +3. **Testing Requirements**: + - Ensure usage and help outputs work as defined under all conditions. +4. **Avoid Redundancy**: + - Help includes usage; there is no need for separate outputs in `help` documentation. diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 000000000..72ffe6fcc --- /dev/null +++ b/docs/logging.md @@ -0,0 +1,146 @@ + +# Go Log Levels + +This rubric provides guidance on how to use log levels (`LogWarn`, `LogError`, `LogTrace`, `LogDebug`, `LogFatal`) consistently. + +--- + +## LogWarn + +**Purpose**: To highlight potentially harmful situations that require attention but do not stop the program from functioning. + +### When to Use + +- A deprecated API or feature is used. +- A retryable failure occurs (e.g., transient network issues, service timeouts). +- An unusual but recoverable condition arises. +- Missing optional configuration or resources (e.g., a default is applied). +- Significant performance degradation is detected. + +### Examples + +- ```console + "Retrying connection to database. Attempt 3 of 5." + ``` + +- ```console + "Configuration value missing, using default." + ``` + +--- + +## LogError + +**Purpose**: To log serious issues that indicate a failure in the application but allow it to continue running (possibly in a degraded state). + +### When to Use + +- A critical operation failed (e.g., failed to write to a persistent store). +- Unexpected exceptions or panics caught in non-critical areas. +- Data integrity issues are detected (e.g., corrupted input). +- Non-recoverable API or system calls fail. + +### Examples + +- ```console + "Failed to persist user data: %v" + ``` + +- ```console + "Unexpected nil pointer dereference at line 42." + ``` + +--- + +## LogTrace + +**Purpose**: To log detailed information useful for understanding program flow, particularly for debugging or performance optimization. + +### When to Use + +- Fine-grained details of function execution. +- Tracing API call flows or middleware behavior. +- Observing request/response lifecycles or context propagation. +- Profiling individual steps in complex operations. + +### Examples + +- ```console + "Entering function 'ProcessRequest' with args: %v" + ``` + +- ```console + "HTTP request headers: %v" + ``` + +--- + +## LogDebug + +**Purpose**: To log information that is useful during development or debugging but not typically needed in production environments. + +### When to Use + +- Diagnosing application logic (e.g., unexpected state transitions). +- Verifying the correctness of logic or assumptions. +- Debugging integration issues (e.g., inspecting external service responses). +- Validating values of configurations, variables, or states. + +### Examples + +- ```console + "Database query executed: %s" + ``` + +- ```console + "Feature toggle '%s' enabled." + ``` + +--- + +## LogFatal + +- **Purpose**: To log a critical error that prevents the application from continuing, and then terminate the application with a non-zero exit code. + +### When to Use + +- A failure occurs that cannot be recovered and requires immediate shutdown. +- Critical initialization steps fail (e.g., missing configuration, database connection failure). +- Irreparable corruption or state inconsistency is detected. + +### Behavior + +- Logs an error message at the `LogError` level. +- Terminates the application using `os.Exit(1)` or an equivalent method. + +### Examples + +- ```console + "Critical failure: Unable to load required configuration. Exiting." + ``` + +- ```console + "Fatal error: Database connection failed. Application shutting down." + ``` + +--- + +## General Guidance + +### Severity Hierarchy** + +Log levels should reflect severity and importance: + +- `LogFatal > LogError > LogWarn > LogDebug > LogTrace`. + +### Production Use (e.g. CI)** + +- `LogError` and `LogWarn` should always be enabled in production to capture issues. +- `LogDebug` and `LogTrace` are often disabled in production to reduce verbosity. + +### Consistency + +- Use structured logging whenever possible (e.g., include fields like `requestID`, `userID`, or `operation`). +- Adopt a centralized logging format (e.g., JSON) for better parsing and analysis. + +This rubric ensures clarity in log messaging, making it easier to diagnose and address issues effectively in any Go application.