Document Atmos Development Conventions #793
Conversation
📝 Walkthrough📝 WalkthroughWalkthroughThis pull request introduces two new documentation files: Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (9)
docs/logging.md (6)
1-7: Consider enhancing the introduction with severity hierarchy.The introduction effectively sets up the document's purpose. Consider adding a brief mention of the severity hierarchy (LogFatal > LogError > LogWarn > LogDebug > LogTrace) upfront to help readers immediately understand the relationship between these levels.
22-28: Consider standardizing code block format and enhancing examples.While the examples are helpful, consider these improvements:
- Use
goinstead ofconsolefor code blocks to better represent actual Go logging calls- Include more context in examples by showing the actual Go logging function calls
Example enhancement:
// Instead of just showing the message "Database query executed: %s" // Show the actual logging call logger.Debug().Str("query", queryString).Msg("Database query executed")Also applies to: 45-51, 68-74, 91-97, 118-124
103-115: Consider adding "Behavior" subsection to all log levels.The LogFatal section uniquely includes a "Behavior" subsection that explains its impact on program execution. Consider adding similar subsections to other log levels to maintain consistency and clarify their effects (e.g., whether they write to stderr/stdout, their impact on performance).
130-131: Fix formatting in section headers.Remove the trailing asterisks from section headers for consistency:
-### Severity Hierarchy** +### Severity Hierarchy -### Production Use (e.g. CI)** +### Production Use (e.g., CI)Also applies to: 136-137
143-144: Consider expanding structured logging guidance.The structured logging section could benefit from concrete examples and more detailed best practices. Consider adding:
- Example of structured vs. unstructured logging
- Common fields that should be included in all logs
- Best practices for field naming conventions
Example addition:
// Unstructured (avoid) logger.Info("User logged in with email: " + email) // Structured (preferred) logger.Info(). Str("event", "user_login"). Str("email", email). Str("request_id", requestID). Str("service", serviceName). Msg("User authentication successful")
138-140: Enhance production logging guidance.Consider adding more specific recommendations for production environments:
- Recommended minimum log levels for different environments (dev, staging, prod)
- Log rotation and retention policies
- Performance implications of different log levels
- Handling of sensitive information in logs
docs/help.md (3)
1-28: Strong start, consider typographical refinements! 💪The definitions and distinctions between usage and help are crystal clear. A minor enhancement would be to use typographic quotes consistently.
-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. +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.🧰 Tools
🪛 LanguageTool
[typographical] ~6-~6: Consider using typographic quotation marks here.
Context: ... in Atmos CLI. It distinguishes between "usage" and "help," clarifies their purposes, a...(EN_QUOTES)
[typographical] ~6-~6: Consider using a typographic opening quote here.
Context: ...I. It distinguishes between "usage" and "help," clarifies their purposes, and out...(EN_QUOTES)
[typographical] ~6-~6: Consider using a typographic close quote here.
Context: ...distinguishes between "usage" and "help," clarifies their purposes, and outlines ...(EN_QUOTES)
31-57: Excellent usage guidelines, consider expanding the example! 🎯The guidelines are clear and practical. The example effectively demonstrates the error scenario.
Consider adding one more example showing invalid argument usage:
Error: Invalid argument value "prod+" for `--stack`. Usage: atmos terraform plan --stack <stack-name> Stack names must contain only alphanumeric characters, hyphens, and underscores.
127-150: Strong conclusion with actionable implementation notes! 🎯The comparison table and implementation notes provide excellent guidance for developers.
Consider adding example test scenarios under "Testing Requirements":
3. **Testing Requirements**: - Ensure usage and help outputs work as defined under all conditions: - Test help display with various flag combinations - Verify error messages in different scenarios - Confirm exit codes match specifications - Validate logo display rules
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
📒 Files selected for processing (2)
docs/help.md(1 hunks)docs/logging.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/help.md
[typographical] ~6-~6: Consider using typographic quotation marks here.
Context: ... in Atmos CLI. It distinguishes between "usage" and "help," clarifies their purposes, a...
(EN_QUOTES)
[typographical] ~6-~6: Consider using a typographic opening quote here.
Context: ...I. It distinguishes between "usage" and "help," clarifies their purposes, and out...
(EN_QUOTES)
[typographical] ~6-~6: Consider using a typographic close quote here.
Context: ...distinguishes between "usage" and "help," clarifies their purposes, and outlines ...
(EN_QUOTES)
docs/logging.md
[uncategorized] ~80-~80: Possible missing comma found.
Context: ...s useful during development or debugging but not typically needed in production envi...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~136-~136: A comma is missing here.
Context: ...Debug > LogTrace. ### Production Use (e.g. CI)** - LogErrorandLogWarn` shoul...
(EG_NO_COMMA)
🔇 Additional comments (1)
docs/help.md (1)
60-124: Solid help guidelines, consider version display consistency! 🛡️
The help guidelines are comprehensive and well-structured. One suggestion regarding the example output:
We should ensure version display consistency across the CLI. Let's verify the current version display format:
✅ Verification successful
The previous search only found markdown files. Let's look for version-related patterns in the actual code to verify the consistency of version display across the CLI.
Version display is consistent across the CLI! 💪
The version display format is consistent throughout the codebase:
- Main version string is managed in
pkg/version/Versionvariable - CLI displays version as "Atmos CLI - Version X.Y.Z" in help output
- Version command shows "🛸 Atmos X.Y.Z on OS/ARCH"
- User-Agent string follows the format "Atmos/X.Y.Z (Cloud Posse; +https://atmos.tools)"
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Check version display format in other help outputs
rg -A 2 "Version" --type md
Length of output: 415
Script:
#!/bin/bash
# Let's check for version display patterns in the code
ast-grep --pattern 'Version $$$'
# Also check for version flag handling
rg -B 2 -A 2 'version|--version|-v' --type go
Length of output: 24424
|
Decide on what to use for logs:
Guidelines:
|
what
why
Summary by CodeRabbit
New Features
Documentation
docs/help.mdoutlining guidelines for displaying usage and help information.docs/logging.mdwith sections on log levels and best practices for logging.