Skip to content

Add installation instructions to minimum CLI version error #4738

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 2 commits into from
Jul 29, 2025
Merged

Add installation instructions to minimum CLI version error #4738

merged 2 commits into from
Jul 29, 2025

Conversation

codyjlandstrom
Copy link
Contributor

Summary

This PR addresses customer feedback that engineers found the minimum CLI version error message confusing because it lacked clear update instructions.

Changes

  • Added helper function in that provides platform-specific installation instructions
  • Enhanced minimum version error message in to include detailed upgrade steps with helpful hints
  • Refactored existing code in to use the new helper function, eliminating code duplication
  • Improved language to avoid repeated 'Alternatively' usage for better readability

Before vs After

Before (confusing for engineers):

unsupported okteto CLI version: 2.99.0

After (clear and actionable):

unsupported okteto CLI version: 2.99.0

Your Okteto instance has a recommended Okteto CLI version of X.X.X and supports a minimum version of Y.Y.Y.

You can update okteto with the following:

curl https://get.okteto.com -sSfL | sh

You can also use:
- macOS: brew upgrade okteto

Alternatively, contact your Okteto administrator.

Testing

  • ✅ All existing tests pass
  • ✅ The existing test continues to work as expected
  • ✅ Code follows existing patterns and error handling conventions

Customer Impact

This directly addresses the customer feedback:

engineers find it confusing that there's no link to the update instructions. They just come to my team for help, and then we tell them how to upgrade.

Now engineers will have clear, actionable instructions right in the error message, reducing support requests and improving the user experience.

@codyjlandstrom
Add installation instructions to minimum CLI version error
ce05730 
- Add GetUpgradeInstructions() helper function with platform-specific instructions
- Update minimum version error in checkCLIVersion() to include detailed upgrade steps
- Refactor displayUpdateSteps() to use new helper function
- Improve language to avoid repeated 'Alternatively' usage

Addresses customer feedback that engineers found the minimum version error
confusing without clear update instructions.
@codyjlandstrom codyjlandstrom requested a review from a team as a code owner July 8, 2025 22:47
@codecov Codecov
Copy link

codecov bot commented Jul 8, 2025 •
edited
Loading

Codecov Report

❌ Patch coverage is 3.84615% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 48.87%. Comparing base (5362ff5) to head (ec05d86).
⚠️ Report is 5 commits behind head on master.

❌ Your patch status has failed because the patch coverage (3.84%) is below the target coverage (60.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files 
@@            Coverage Diff             @@
##           master    #4738      +/-   ##
==========================================
- Coverage   48.91%   48.87%   -0.04%     
==========================================
  Files         356      356              
  Lines       29807    29817      +10     
==========================================
- Hits        14580    14574       -6     
- Misses      14066    14080      +14     
- Partials     1161     1163       +2
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@jLopezbarb
Copy link
Contributor

For this, I think we should check which okteto is the one used and how it's installed. If for example a user has 2 different versions, like usually happens on mac that we recommend using: curl https://get.okteto.com -sSfL | sh it will install it on the PATH, using brew it will install on its own PATH, if the user has a custom PATH and the CLI binary was downloaded from github releases it could be using another one.
This was something that we discussed when introduced the okteto version command. I'm ok with going with this but We've to remember that this will work most of the times but there could be some that it won't be working

@codyjlandstrom
Address jLopezbarb feedback: improve upgrade instructions
ec05d86 
- Add guidance to check current installation method first
- Provide specific instructions for different installation methods
- Include warning about potential multiple installations
- Add PATH troubleshooting note

This addresses the concern that users may have multiple okteto installations
and need method-specific upgrade instructions.
@codyjlandstrom
Copy link
Contributor Author

Thanks for the excellent feedback @jLopezbarb! You're absolutely right about the potential issues with multiple installations.

I've updated the upgrade instructions to address your concerns:

Changes Made:

  1. Added installation detection step: Now instructs users to first run which okteto (or where okteto on Windows) to identify their current installation
  2. Method-specific instructions: Provides separate upgrade steps for each installation method:
    • Script installation: curl https://get.okteto.com -sSfL | sh
    • Brew installation: brew upgrade okteto
    • Manual download: GitHub releases link
    • Scoop (Windows): scoop update okteto
  3. Multiple installation warning: Added explicit note about potential multiple installations and PATH conflicts
  4. Troubleshooting guidance: Suggests checking PATH if issues persist

Example of New Message:

Your Okteto instance has a recommended Okteto CLI version of X.X.X and supports a minimum version of Y.Y.Y.

You can update okteto with the following:

First, check your current installation: which okteto

Then upgrade using the method you originally used:
- If installed via script: curl https://get.okteto.com -sSfL | sh
- If installed via brew: brew upgrade okteto
- If manually downloaded: Download from https://github.com/okteto/okteto/releases

Note: Multiple installations may exist. Check your PATH if issues persist.

Alternatively, contact your Okteto administrator.

This approach acknowledges the complexity you mentioned while still providing actionable guidance. Users will now be more aware of potential conflicts and have better tools to diagnose their specific situation.

What do you think of this approach?

@github-actions GitHub Actions
Copy link
Contributor

This pull request is stale because it has been open for 15 days with no activity. Comment on this pull request or it will be closed in 7 days

@github-actions github-actions bot added the stale label Jul 25, 2025
@jLopezbarb jLopezbarb merged commit d01dd7e into master Jul 29, 2025
11 of 13 checks passed
@jLopezbarb jLopezbarb deleted the okteto/workspace-e6rlP26I branch July 29, 2025 09:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jLopezbarb jLopezbarb jLopezbarb approved these changes

Assignees
No one assigned
Labels
release/internal stale
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@codyjlandstrom @jLopezbarb