Document Atmos Development Conventions

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 <stack-name>
+     ```
+
+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 <command> [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 (optional for subcommands)     |
+| **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.

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.