Skip to content

Standardize Help and Usage content for all commands and sub commands#914

Merged
aknysh merged 78 commits intomainfrom
feature/dev-2896-incorrect-output-for-atmos-validate
Jan 18, 2025
Merged

Standardize Help and Usage content for all commands and sub commands#914
aknysh merged 78 commits intomainfrom
feature/dev-2896-incorrect-output-for-atmos-validate

Conversation

@samtholiya
Copy link
Collaborator

@samtholiya samtholiya commented Jan 5, 2025

what

  • Every command will have intutively display help and usage
    Example usage scenarios:
    image
    Example help scenarios:
    image
    image
    image

Example atmos config error code
image

Example alias subCommand section
image

why

  • Help and usage displays were not consistently handled across multiple commands

references

Summary by CodeRabbit

Release Notes

Command Line Interface Improvements

  • Enhanced command argument validation across multiple commands, enforcing stricter command usage.
  • Added robust help request handling for various commands.
  • Improved error messaging for unknown commands and streamlined command execution processes.

New Features

  • Introduced new Helmfile sub-commands:
    • helmfile apply
    • helmfile destroy
    • helmfile diff
    • helmfile sync
  • Added custom colored command-line output support.
  • Introduced a new function for printing error messages in color.

Command Behavior Changes

  • Most commands now explicitly reject additional arguments.
  • Simplified help and usage display mechanisms.
  • Removed automatic help information for empty subcommands.
  • Updated command usage syntax to emphasize sub-commands.
  • Introduced sub-command aliases for improved usability.

Dependency Updates

  • Removed coloredcobra library.
  • Added golang.org/x/oauth2 dependency.

Usability Enhancements

  • More consistent command-line interface with improved error handling and messaging.
  • Enhanced template generation for command help.
  • Added support for displaying subcommand aliases in help templates.

dev-2821-atmos-terraform-help-should-also-show-terraform-help
…terraform-help' of https://github.com/cloudposse/atmos into feature/dev-2821-atmos-terraform-help-should-also-show-terraform-help
…terraform-help' of https://github.com/cloudposse/atmos into feature/dev-2821-atmos-terraform-help-should-also-show-terraform-help
@samtholiya samtholiya changed the base branch from main to feature/dev-2821-atmos-terraform-help-should-also-show-terraform-help January 5, 2025 19:29
@mergify mergify bot added the triage Needs triage label Jan 5, 2025
@mergify
Copy link

mergify bot commented Jan 5, 2025

💥 This pull request now has conflicts. Could you fix it @samtholiya? 🙏

@mergify mergify bot added the conflict This PR has conflicts label Jan 5, 2025
@aknysh
Copy link
Member

aknysh commented Jan 17, 2025

@samtholiya please resolve the conflicts

@mergify mergify bot removed the conflict This PR has conflicts label Jan 18, 2025
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (3)
cmd/root.go (2)

133-145: Consider adding input validation.

The function handles the happy path well, but could benefit from input validation.

Consider this enhancement:

 func getInvalidCommandName(input string) string {
+  if input == "" {
+    return ""
+  }
   // Regular expression to match the command name inside quotes
   re := regexp.MustCompile(`unknown command "([^"]+)"`)

Line range hint 179-207: Consider simplifying help function logic.

The help function handles errors well but the logic flow could be more straightforward.

Consider extracting the logo printing logic into a separate function to reduce duplication:

+func printAtmosLogo() error {
+  fmt.Println()
+  return tuiUtils.PrintStyledText("ATMOS")
+}
+
 RootCmd.SetHelpFunc(func(command *cobra.Command, args []string) {
   // ... existing conditions ...
-  fmt.Println()
-  err := tuiUtils.PrintStyledText("ATMOS")
+  err := printAtmosLogo()
   if err != nil {
     u.LogErrorAndExit(atmosConfig, err)
   }
   // ... rest of the function ...
cmd/terraform.go (1)

39-41: Consider using handleHelpRequest for consistent help handling.

Since this PR aims to standardize help and usage content, consider using the new handleHelpRequest utility function mentioned in the PR summary.

 	if info.NeedHelp {
-		actualCmd.Usage()
-		return
+		return handleHelpRequest(actualCmd)
 	}
🧰 Tools
🪛 golangci-lint (1.62.2)

40-40: Error return value of actualCmd.Usage is not checked

(errcheck)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c7ee7e7 and ac22b72.

⛔ Files ignored due to path filters (1)
  • go.sum is excluded by !**/*.sum
📒 Files selected for processing (9)
  • cmd/root.go (6 hunks)
  • cmd/terraform.go (3 hunks)
  • cmd/version.go (1 hunks)
  • go.mod (0 hunks)
  • internal/tui/templates/templater.go (5 hunks)
  • pkg/utils/log_utils.go (1 hunks)
  • tests/snapshots/TestCLICommands_check_atmos_--help_in_empty-dir.stdout.golden (3 hunks)
  • tests/test-cases/core.yaml (1 hunks)
  • tests/test-cases/empty-dir.yaml (2 hunks)
💤 Files with no reviewable changes (1)
  • go.mod
🚧 Files skipped from review as they are similar to previous changes (4)
  • cmd/version.go
  • tests/test-cases/core.yaml
  • pkg/utils/log_utils.go
  • internal/tui/templates/templater.go
🧰 Additional context used
🪛 golangci-lint (1.62.2)
cmd/terraform.go

40-40: Error return value of actualCmd.Usage is not checked

(errcheck)

⏰ Context from checks skipped due to timeout of 90000ms (2)
  • GitHub Check: Build (windows-latest, windows)
  • GitHub Check: Summary
🔇 Additional comments (7)
tests/snapshots/TestCLICommands_check_atmos_--help_in_empty-dir.stdout.golden (2)

28-31: Well done on adding command aliases!

The addition of aliases hf and tf for commonly used commands will improve developer productivity. This is a great quality-of-life enhancement.


6-6: Strong work on standardizing command terminology!

The consistent use of [sub-command] notation and updated example usage improves clarity. This aligns well with the PR's objective of standardizing help content.

Also applies to: 59-59, 62-62

tests/test-cases/empty-dir.yaml (2)

31-31: Good catch on the exit code!

Changing the exit code to 1 when config is missing is more appropriate. This follows the Unix convention where non-zero exit codes indicate errors.


45-45: Consistent terminology in test expectations.

The updated help text matches the new standardized terminology using "subcommand". This maintains consistency across the codebase.

cmd/root.go (1)

7-8: LGTM! Good additions for enhanced functionality.

The new imports and FParseErrWhitelist field are well-chosen for improving command parsing flexibility and error handling.

Also applies to: 13-13, 30-30

cmd/terraform.go (2)

7-7: LGTM! Clean import addition.

The cobra import is properly formatted and essential for the CLI functionality.


22-24: Verify hook execution with the new config info retrieval!

The refactoring looks good! The use of getConfigAndStacksInfo simplifies the implementation while maintaining hook functionality.

Let's verify the hook execution still works as expected:

✅ Verification successful

Hook execution verified - Implementation is battle-ready! 💪

The refactoring maintains a solid execution flow:

  • getConfigAndStacksInfo properly processes command arguments and generates the required configuration
  • hooks.RunE correctly receives and handles the configuration info
  • Error handling is robust throughout the execution chain
🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Check if hooks are properly registered and called
rg -A 5 "RunE.*info" pkg/hooks/

Length of output: 357


Script:

#!/bin/bash
# Check getConfigAndStacksInfo implementation
ast-grep --pattern 'func getConfigAndStacksInfo($$$) $$$'

# Look for hook-related code and tests
rg -g '!vendor' -A 5 'hooks\.' cmd/
rg -g '!vendor' -l 'hooks.*test' .

Length of output: 1409

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🔭 Outside diff range comments (1)
tests/test-cases/log-level-validation.yaml (1)

Warrior, your instincts serve you well. These test changes indeed stray from our mission.

The log level validation tests appear to be unrelated to the PR's objective of standardizing help and usage content. The code search reveals that while log level validation is an existing feature in the codebase (in pkg/config/), these test additions are not connected to any help/usage content standardization efforts.

🔗 Analysis chain

Line range hint 1-80: Verify alignment with PR objectives.

Spartan, these test changes seem unrelated to the PR's objective of standardizing help and usage content. The modifications to log level validation behavior appear to be outside the scope of the current changes.

Let me check if there are related changes in other files:

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Search for related changes in help/usage standardization
rg -l "cobra.NoArgs|handleHelpRequest|showUsageAndExit" --type go

# Check if log level validation is modified elsewhere
git diff | grep -A 5 "logs-level"

Length of output: 904


Script:

#!/bin/bash
# Search for log level validation code
ast-grep --pattern 'Invalid log level.*Valid options'

# Search for log level related code
rg "ATMOS_LOGS_LEVEL|--logs-level" --type go -A 3

# Check for other test changes in the same PR
git diff -- 'tests/**/*.yaml'

Length of output: 1298


Script:

#!/bin/bash
# Search for help/usage message changes
git diff -U0 | rg "Usage:|Error:" -B2 -A2

# Check for cobra command changes related to error messages
rg "cobra.*Error" --type go -A 3

Length of output: 78

🧹 Nitpick comments (1)
tests/snapshots/TestCLICommands_atmos_--help.stdout.golden (1)

Line range hint 1-62: Consider adding examples for the new aliases.

While the aliases are well-documented, consider enhancing the example section to demonstrate their usage. This would help users quickly understand how to leverage these shortcuts.

Add examples like:

  atmos atmos [subcommand] <component> -s <stack> -- <native-flags>
+ 
+ Examples using aliases:
+   atmos tf plan <component> -s <stack>    # Same as: atmos terraform plan
+   atmos hf diff <component> -s <stack>    # Same as: atmos helmfile diff
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ac22b72 and 1858b86.

⛔ Files ignored due to path filters (1)
  • go.sum is excluded by !**/*.sum
📒 Files selected for processing (3)
  • go.mod (0 hunks)
  • tests/snapshots/TestCLICommands_atmos_--help.stdout.golden (3 hunks)
  • tests/test-cases/log-level-validation.yaml (3 hunks)
💤 Files with no reviewable changes (1)
  • go.mod
⏰ Context from checks skipped due to timeout of 90000ms (5)
  • GitHub Check: Build (macos-latest, macos)
  • GitHub Check: Build (windows-latest, windows)
  • GitHub Check: Build (ubuntu-latest, linux)
  • GitHub Check: Analyze (go)
  • GitHub Check: Summary
🔇 Additional comments (5)
tests/snapshots/TestCLICommands_atmos_--help.stdout.golden (4)

6-6: LGTM! Clear and consistent usage syntax.

The updated syntax atmos [sub-command] [flags] is more precise and aligns with the standardization goals. The explicit mention of [flags] helps users understand all possible command elements.


28-32: Excellent addition of command aliases!

The new SubCommand Aliases section introduces helpful shortcuts (hf for helmfile, tf for terraform) that will improve the CLI experience. These aliases target frequently used commands, making the CLI more efficient to use.


59-59: LGTM! Example follows the new terminology.

The example usage maintains consistency with the new [subcommand] terminology while preserving the clear structure for component and stack parameters.


62-62: LGTM! Help reference matches new terminology.

The help command reference consistently uses [subcommand], maintaining the standardized terminology throughout the documentation.

tests/test-cases/log-level-validation.yaml (1)

48-48: ⚠️ Potential issue

Review test expectations for valid log levels.

Spartan, these changes appear to be introducing incorrect behavior. The test cases for valid log levels (in config file, environment variable, and command line flag) now expect failure (exit code 1) where they previously expected success (exit code 0). Valid inputs should succeed, not fail.

Consider the following points:

  • Valid log levels like "Debug" and "Info" are legitimate values
  • Failing on valid input would break existing functionality
  • This change contradicts standard CLI behavior where valid inputs succeed

Let's verify the intended behavior:

Also applies to: 64-64, 80-80

Copy link
Member

@aknysh aknysh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@aknysh aknysh merged commit b8f480f into main Jan 18, 2025
44 checks passed
@aknysh aknysh deleted the feature/dev-2896-incorrect-output-for-atmos-validate branch January 18, 2025 18:54
@github-actions
Copy link

These changes were released in v1.152.0.

@coderabbitai coderabbitai bot mentioned this pull request Apr 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

minor New features that do not break anything

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants