diff --git a/docs.json b/docs.json index fd428f67..eace62f7 100644 --- a/docs.json +++ b/docs.json @@ -20,36 +20,22 @@ "navigation": { "tabs": [ { - "tab": "Documentation", + "tab": "Overview", "pages": [ { - "group": "Get Started", + "group": "Overview", "pages": [ "overview/introduction", "overview/quickstart", - "openhands/usage/get-started/tutorials" + "overview/first-projects", + "overview/faqs", + "overview/community", + "overview/contributing" ] }, { - "group": "Essential Guidelines", + "group": "Common Features", "pages": [ - "openhands/usage/essential-guidelines/when-to-use-openhands", - "openhands/usage/tips/prompting-best-practices", - "openhands/usage/essential-guidelines/good-vs-bad-instructions", - "openhands/usage/essential-guidelines/sdlc-integration" - ] - }, - { - "group": "Onboarding OpenHands", - "pages": [ - "openhands/usage/customization/repository", - "overview/skills/repo" - ] - }, - { - "group": "Product Guides", - "pages": [ - "openhands/usage/key-features", "overview/model-context-protocol", { "group": "Skills", @@ -60,164 +46,95 @@ "overview/skills/org", "overview/skills/public" ] - }, - "openhands/usage/settings/secrets-settings", - { - "group": "Settings", - "pages": [ - "openhands/usage/settings/application-settings", - "openhands/usage/settings/llm-settings", - "openhands/usage/settings/integrations-settings", - "openhands/usage/settings/secrets-settings", - "openhands/usage/settings/api-keys-settings", - "openhands/usage/settings/mcp-settings" - ] - }, - { - "group": "OpenHands Cloud", - "pages": [ - "openhands/usage/cloud/openhands-cloud", - "openhands/usage/cloud/cloud-ui" - ] } ] }, { - "group": "Integrations", + "group": "Tips and Tricks", "pages": [ - "openhands/usage/settings/integrations-settings", - "openhands/usage/cloud/github-installation", - "openhands/usage/cloud/gitlab-installation", - "openhands/usage/cloud/bitbucket-installation", - "openhands/usage/cloud/slack-installation", - "openhands/usage/cloud/project-management/jira-integration", - { - "group": "Cloud API", - "pages": [ - "openhands/usage/cloud/cloud-api", - "openhands/usage/api/v1" - ] - } + "openhands/usage/tips/prompting-best-practices" ] }, { - "group": "CLI", + "group": "Help", "pages": [ - { - "group": "Getting Started", - "pages": [ - "openhands/usage/cli/installation", - "openhands/usage/cli/quick-start" - ] - }, - { - "group": "Ways to Run", - "pages": [ - "openhands/usage/cli/terminal", - "openhands/usage/cli/headless", - "openhands/usage/cli/web-interface", - "openhands/usage/cli/gui-server", - { - "group": "IDE Integration (ACP)", - "pages": [ - "openhands/usage/cli/ide/overview", - "openhands/usage/cli/ide/zed", - "openhands/usage/cli/ide/toad", - "openhands/usage/cli/ide/vscode", - "openhands/usage/cli/ide/jetbrains" - ] - } - ] - }, - { - "group": "Cloud", - "pages": [ - "openhands/usage/cli/cloud" - ] - }, - { - "group": "Extensions", - "pages": [ - "openhands/usage/cli/mcp-servers", - "openhands/usage/cli/critic" - ] - }, - { - "group": "Reference", - "pages": [ - "openhands/usage/cli/command-reference", - "openhands/usage/cli/resume" - ] - } + "openhands/usage/troubleshooting/troubleshooting", + "openhands/usage/troubleshooting/feedback" + ] + } + ] + }, + { + "tab": "Web", + "pages": [ + { + "group": "Key Features", + "pages": [ + "openhands/usage/key-features" ] }, { - "group": "Additional Documentation", + "group": "OpenHands Cloud", "pages": [ + "openhands/usage/cloud/openhands-cloud", { - "group": "V0 Reference", + "group": "Integrations", "pages": [ - "openhands/usage/v0/runtimes/V0_overview", + "openhands/usage/cloud/bitbucket-installation", + "openhands/usage/cloud/github-installation", + "openhands/usage/cloud/gitlab-installation", + "openhands/usage/cloud/slack-installation", { - "group": "V0 Runtime Providers", + "group": "Project Management Tools", "pages": [ - "openhands/usage/v0/runtimes/V0_docker", - "openhands/usage/v0/runtimes/V0_remote", - "openhands/usage/v0/runtimes/V0_local", - { - "group": "V0 Third-Party Providers", - "pages": [ - "openhands/usage/v0/runtimes/V0_modal", - "openhands/usage/v0/runtimes/V0_daytona", - "openhands/usage/v0/runtimes/V0_runloop", - "openhands/usage/v0/runtimes/V0_e2b" - ] - } + "openhands/usage/cloud/project-management/jira-integration" ] - }, - "openhands/usage/v0/advanced/V0_configuration-options", - { - "group": "V0 REST API", - "openapi": "openapi/V0_openapi.json" } ] }, + "openhands/usage/cloud/cloud-ui", + "openhands/usage/cloud/cloud-api" + ] + }, + { + "group": "Local GUI", + "pages": [ + "openhands/usage/run-openhands/local-setup", + "openhands/usage/run-openhands/gui-mode" + ] + }, + { + "group": "REST API", + "pages": [ + "openhands/usage/api/v1" + ] + }, + { + "group": "Customizations & Settings", + "pages": [ { - "group": "Local GUI", + "group": "OpenHands Settings", "pages": [ - "openhands/usage/run-openhands/local-setup", - "openhands/usage/run-openhands/gui-mode", - "openhands/usage/troubleshooting/troubleshooting", - { - "group": "Sandbox Configuration", - "pages": [ - "openhands/usage/sandboxes/overview", - { - "group": "Sandbox Providers", - "pages": [ - "openhands/usage/sandboxes/docker", - "openhands/usage/sandboxes/remote", - "openhands/usage/sandboxes/process" - ] - } - ] - }, - { - "group": "Advanced", - "pages": [ - "openhands/usage/advanced/configuration-options", - "openhands/usage/advanced/custom-sandbox-guide", - "openhands/usage/advanced/search-engine-setup" - ] - } + "openhands/usage/settings/application-settings", + "openhands/usage/settings/llm-settings", + "openhands/usage/settings/integrations-settings", + "openhands/usage/settings/secrets-settings", + "openhands/usage/settings/api-keys-settings", + "openhands/usage/settings/mcp-settings" ] }, + "openhands/usage/customization/repository" + ] + }, + { + "group": "Advanced Configuration", + "pages": [ { "group": "LLM Configuration", "pages": [ "openhands/usage/llms/llms", { - "group": "LLM Providers", + "group": "Providers", "pages": [ "openhands/usage/llms/openhands-llms", "openhands/usage/llms/azure-llms", @@ -233,42 +150,113 @@ ] }, { - "group": "Developers", + "group": "Sandbox Configuration", "pages": [ - "openhands/usage/developers/development-overview", - "openhands/usage/developers/debugging", - "openhands/usage/developers/websocket-connection", - "openhands/usage/developers/evaluation-harness" + "openhands/usage/sandboxes/overview", + { + "group": "Providers", + "pages": [ + "openhands/usage/sandboxes/docker", + "openhands/usage/sandboxes/remote", + "openhands/usage/sandboxes/process" + ] + } ] }, + "openhands/usage/advanced/configuration-options", + "openhands/usage/advanced/custom-sandbox-guide", + "openhands/usage/advanced/search-engine-setup" + ] + } + ] + }, + { + "tab": "Web (V0)", + "pages": [ + { + "group": "V0 Runtime Configuration", + "pages": [ + "openhands/usage/v0/runtimes/V0_overview", { - "group": "Community", + "group": "Providers", "pages": [ - "overview/community", - "overview/contributing", - "overview/faqs", - "openhands/usage/troubleshooting/feedback" + "openhands/usage/v0/runtimes/V0_docker", + "openhands/usage/v0/runtimes/V0_remote", + "openhands/usage/v0/runtimes/V0_local", + { + "group": "Third-Party Providers", + "pages": [ + "openhands/usage/v0/runtimes/V0_modal", + "openhands/usage/v0/runtimes/V0_daytona", + "openhands/usage/v0/runtimes/V0_runloop", + "openhands/usage/v0/runtimes/V0_e2b" + ] + } ] } ] + }, + { + "group": "V0 Configuration Options", + "pages": [ + "openhands/usage/v0/advanced/V0_configuration-options" + ] + }, + { + "group": "V0 REST API", + "openapi": "openapi/V0_openapi.json" } ] }, { - "tab": "Use Cases", + "tab": "CLI", "pages": [ { - "group": "Use Cases", + "group": "Getting Started", + "pages": [ + "openhands/usage/cli/installation", + "openhands/usage/cli/quick-start" + ] + }, + { + "group": "Ways to Run", + "pages": [ + "openhands/usage/cli/terminal", + "openhands/usage/cli/headless", + "openhands/usage/cli/web-interface", + "openhands/usage/cli/gui-server", + { + "group": "IDE Integration (ACP)", + "pages": [ + "openhands/usage/cli/ide/overview", + "openhands/usage/cli/ide/zed", + "openhands/usage/cli/ide/toad", + "openhands/usage/cli/ide/vscode", + "openhands/usage/cli/ide/jetbrains" + ] + } + ] + }, + { + "group": "Cloud", + "pages": [ + "openhands/usage/cli/cloud" + ] + }, + { + "group": "Extensions", + "pages": [ + "openhands/usage/cli/mcp-servers", + "openhands/usage/cli/critic" + ] + }, + { + "group": "Reference", "pages": [ - "openhands/usage/use-cases/vulnerability-remediation", - "openhands/usage/use-cases/code-review", - "openhands/usage/use-cases/incident-triage", - "openhands/usage/use-cases/cobol-modernization", - "openhands/usage/use-cases/dependency-upgrades", - "openhands/usage/use-cases/spark-migrations" + "openhands/usage/cli/command-reference", + "openhands/usage/cli/resume" ] } - ] }, { diff --git a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx deleted file mode 100644 index 0fe82d8a..00000000 --- a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx +++ /dev/null @@ -1,433 +0,0 @@ ---- -title: TODO-Good vs. Bad Instructions -description: Learn how to write effective instructions for OpenHands ---- - -The quality of your instructions directly impacts the quality of OpenHands' output. This guide shows concrete examples of good and bad prompts, explains why some work better than others, and provides principles for writing effective instructions. - -## Concrete Examples of Good/Bad Prompts - -### Bug Fixing Examples - -#### Bad Example - -``` -Fix the bug in my code. -``` - -**Why it's bad:** -- No information about what the bug is -- No indication of where to look -- No description of expected vs. actual behavior -- OpenHands would have to guess what's wrong - -#### Good Example - -``` -Fix the TypeError in src/api/users.py line 45. - -Error message: -TypeError: 'NoneType' object has no attribute 'get' - -Expected behavior: The get_user_preferences() function should return -default preferences when the user has no saved preferences. - -Actual behavior: It crashes with the error above when user.preferences is None. - -The fix should handle the None case gracefully and return DEFAULT_PREFERENCES. -``` - -**Why it works:** -- Specific file and line number -- Exact error message -- Clear expected vs. actual behavior -- Suggested approach for the fix - -### Feature Development Examples - -#### Bad Example - -``` -Add user authentication to my app. -``` - -**Why it's bad:** -- Scope is too large and undefined -- No details about authentication requirements -- No mention of existing code or patterns -- Could mean many different things - -#### Good Example - -``` -Add email/password login to our Express.js API. - -Requirements: -1. POST /api/auth/login endpoint -2. Accept email and password in request body -3. Validate against users in PostgreSQL database -4. Return JWT token on success, 401 on failure -5. Use bcrypt for password comparison (already in dependencies) - -Follow the existing patterns in src/api/routes.js for route structure. -Use the existing db.query() helper in src/db/index.js for database access. - -Success criteria: I can call the endpoint with valid credentials -and receive a JWT token that works with our existing auth middleware. -``` - -**Why it works:** -- Specific, scoped feature -- Clear technical requirements -- Points to existing patterns to follow -- Defines what "done" looks like - -### Code Review Examples - -#### Bad Example - -``` -Review my code. -``` - -**Why it's bad:** -- No code provided or referenced -- No indication of what to look for -- No context about the code's purpose -- No criteria for the review - -#### Good Example - -``` -Review this pull request for our payment processing module: - -Focus areas: -1. Security - we're handling credit card data -2. Error handling - payments must never silently fail -3. Idempotency - duplicate requests should be safe - -Context: -- This integrates with Stripe API -- It's called from our checkout flow -- We have ~10,000 transactions/day - -Please flag any issues as Critical/Major/Minor with explanations. -``` - -**Why it works:** -- Clear scope and focus areas -- Important context provided -- Business implications explained -- Requested output format specified - -### Refactoring Examples - -#### Bad Example - -``` -Make the code better. -``` - -**Why it's bad:** -- "Better" is subjective and undefined -- No specific problems identified -- No goals for the refactoring -- No constraints or requirements - -#### Good Example - -``` -Refactor the UserService class in src/services/user.js: - -Problems to address: -1. The class is 500+ lines - split into smaller, focused services -2. Database queries are mixed with business logic - separate them -3. There's code duplication in the validation methods - -Constraints: -- Keep the public API unchanged (other code depends on it) -- Maintain test coverage (run npm test after changes) -- Follow our existing service patterns in src/services/ - -Goal: Improve maintainability while keeping the same functionality. -``` - -**Why it works:** -- Specific problems identified -- Clear constraints and requirements -- Points to patterns to follow -- Measurable success criteria - -## Key Principles for Effective Instructions - -### Be Specific - -Vague instructions produce vague results. Be concrete about: - -| Instead of... | Say... | -|---------------|--------| -| "Fix the error" | "Fix the TypeError on line 45 of api.py" | -| "Add tests" | "Add unit tests for the calculateTotal function covering edge cases" | -| "Improve performance" | "Reduce the database queries from N+1 to a single join query" | -| "Clean up the code" | "Extract the validation logic into a separate ValidatorService class" | - -### Provide Context - -Help OpenHands understand the bigger picture: - -``` -Context to include: -- What does this code do? (purpose) -- Who uses it? (users/systems) -- Why does this matter? (business impact) -- What constraints exist? (performance, compatibility) -- What patterns should be followed? (existing conventions) -``` - -**Example with context:** - -``` -Add rate limiting to our public API endpoints. - -Context: -- This is a REST API serving mobile apps and third-party integrations -- We've been seeing abuse from web scrapers hitting us 1000+ times/minute -- Our infrastructure can handle 100 req/sec per client sustainably -- We use Redis (already available in the project) -- Our API follows the controller pattern in src/controllers/ - -Requirement: Limit each API key to 100 requests per minute with -appropriate 429 responses and Retry-After headers. -``` - -### Set Clear Goals - -Define what success looks like: - -``` -Success criteria checklist: -✓ What specific outcome do you want? -✓ How will you verify it worked? -✓ What tests should pass? -✓ What should the user experience be? -``` - -**Example with clear goals:** - -``` -Implement password reset functionality. - -Success criteria: -1. User can request reset via POST /api/auth/forgot-password -2. System sends email with secure reset link -3. Link expires after 1 hour -4. User can set new password via POST /api/auth/reset-password -5. Old sessions are invalidated after password change -6. All edge cases return appropriate error messages -7. Existing tests still pass, new tests cover the feature -``` - -### Include Constraints - -Specify what you can't or won't change: - -``` -Constraints to specify: -- API compatibility (can't break existing clients) -- Technology restrictions (must use existing stack) -- Performance requirements (must respond in <100ms) -- Security requirements (must not log PII) -- Time/scope limits (just this one file) -``` - -## Common Pitfalls to Avoid - -### Vague Requirements - - - - ``` - Make the dashboard faster. - ``` - - - ``` - The dashboard takes 5 seconds to load. - - Profile it and optimize to load in under 1 second. - - Likely issues: - - N+1 queries in getWidgetData() - - Uncompressed images - - Missing database indexes - - Focus on the biggest wins first. - ``` - - - -### Missing Context - - - - ``` - Add caching to the API. - ``` - - - ``` - Add caching to the product catalog API. - - Context: - - 95% of requests are for the same 1000 products - - Product data changes only via admin panel (rare) - - We already have Redis running for sessions - - Current response time is 200ms, target is <50ms - - Cache strategy: Cache product data in Redis with 5-minute TTL, - invalidate on product update. - ``` - - - -### Unrealistic Expectations - - - - ``` - Rewrite our entire backend from PHP to Go. - ``` - - - ``` - Create a Go microservice for the image processing currently in - src/php/ImageProcessor.php. - - This is the first step in our gradual migration. - The Go service should: - 1. Expose the same API endpoints - 2. Be deployable alongside the existing PHP app - 3. Include a feature flag to route traffic - - Start with just the resize and crop functions. - ``` - - - -### Incomplete Information - - - - ``` - The login is broken, fix it. - ``` - - - ``` - Users can't log in since yesterday's deployment. - - Symptoms: - - Login form submits but returns 500 error - - Server logs show: "Redis connection refused" - - Redis was moved to a new host yesterday - - The issue is likely in src/config/redis.js which may - have the old host hardcoded. - - Expected: Login should work with the new Redis at redis.internal:6380 - ``` - - - -## Best Practices - -### Structure Your Instructions - -Use clear structure for complex requests: - -``` -## Task -[One sentence describing what you want] - -## Background -[Context and why this matters] - -## Requirements -1. [Specific requirement] -2. [Specific requirement] -3. [Specific requirement] - -## Constraints -- [What you can't change] -- [What must be preserved] - -## Success Criteria -- [How to verify it works] -``` - -### Provide Examples - -Show what you want through examples: - -``` -Add input validation to the user registration endpoint. - -Example of what validation errors should look like: - -{ - "error": "validation_failed", - "details": [ - {"field": "email", "message": "Invalid email format"}, - {"field": "password", "message": "Must be at least 8 characters"} - ] -} - -Validate: -- email: valid format, not already registered -- password: min 8 chars, at least 1 number -- username: 3-20 chars, alphanumeric only -``` - -### Define Success Criteria - -Be explicit about what "done" means: - -``` -This task is complete when: -1. All existing tests pass (npm test) -2. New tests cover the added functionality -3. The feature works as described in the acceptance criteria -4. Code follows our style guide (npm run lint passes) -5. Documentation is updated if needed -``` - -### Iterate and Refine - -Build on previous work: - -``` -In our last session, you added the login endpoint. - -Now add the logout functionality: -1. POST /api/auth/logout endpoint -2. Invalidate the current session token -3. Clear any server-side session data -4. Follow the same patterns used in login - -The login implementation is in src/api/auth/login.js for reference. -``` - -## Quick Reference - -| Element | Bad | Good | -|---------|-----|------| -| Location | "in the code" | "in src/api/users.py line 45" | -| Problem | "it's broken" | "TypeError when user.preferences is None" | -| Scope | "add authentication" | "add JWT-based login endpoint" | -| Behavior | "make it work" | "return 200 with user data on success" | -| Patterns | (none) | "follow patterns in src/services/" | -| Success | (none) | "all tests pass, endpoint returns correct data" | - - -The investment you make in writing clear instructions pays off in fewer iterations, better results, and less time debugging miscommunication. Take the extra minute to be specific. - diff --git a/openhands/usage/essential-guidelines/sdlc-integration.mdx b/openhands/usage/essential-guidelines/sdlc-integration.mdx deleted file mode 100644 index 92931852..00000000 --- a/openhands/usage/essential-guidelines/sdlc-integration.mdx +++ /dev/null @@ -1,497 +0,0 @@ ---- -title: TODO-OpenHands in Your SDLC -description: How OpenHands fits into your software development lifecycle ---- - -OpenHands can enhance every phase of your software development lifecycle (SDLC), from planning through deployment. This guide shows how to integrate OpenHands into your development workflows effectively. - -## Integration with Development Workflows - -### Planning Phase - -Use OpenHands during planning to accelerate technical decisions: - -**Technical specification assistance:** -``` -Create a technical specification for adding search functionality: - -Requirements from product: -- Full-text search across products and articles -- Filter by category, price range, and date -- Sub-200ms response time at 1000 QPS - -Provide: -1. Architecture options (Elasticsearch vs. PostgreSQL full-text) -2. Data model changes needed -3. API endpoint designs -4. Estimated implementation effort -5. Risks and mitigations -``` - -**Sprint planning support:** -``` -Review these user stories and create implementation tasks: - -Story 1: As a user, I can reset my password via email -Story 2: As an admin, I can view user activity logs - -For each story, create: -- Technical subtasks -- Estimated effort (hours) -- Dependencies on other work -- Testing requirements -``` - -### Development Phase - -OpenHands excels during active development: - -**Feature implementation:** -- Write new features with clear specifications -- Follow existing code patterns automatically -- Generate tests alongside code -- Create documentation as you go - -**Bug fixing:** -- Analyze error logs and stack traces -- Identify root causes -- Implement fixes with regression tests -- Document the issue and solution - -**Code improvement:** -- Refactor for clarity and maintainability -- Optimize performance bottlenecks -- Update deprecated APIs -- Improve error handling - -### Testing Phase - -Automate test creation and improvement: - -``` -Add comprehensive tests for the UserService module: - -Current coverage: 45% -Target coverage: 85% - -1. Analyze uncovered code paths -2. Write unit tests for edge cases -3. Add integration tests for API endpoints -4. Create test data factories -5. Document test scenarios -``` - -### Review Phase - -Accelerate code reviews: - -``` -Review this PR for our coding standards: - -Check for: -1. Security issues (SQL injection, XSS, etc.) -2. Performance concerns -3. Test coverage adequacy -4. Documentation completeness -5. Adherence to our style guide - -Provide actionable feedback with severity ratings. -``` - -### Deployment Phase - -Assist with deployment preparation: - -``` -Prepare for production deployment: - -1. Review all changes since last release -2. Check for breaking API changes -3. Verify database migrations are reversible -4. Update the changelog -5. Create release notes -6. Identify rollback steps if needed -``` - -## CI/CD Integration - -### GitHub Actions Integration - -Integrate OpenHands into your GitHub workflows: - -```yaml -# .github/workflows/openhands-assist.yml -name: OpenHands Assist - -on: - issues: - types: [opened, labeled] - pull_request: - types: [opened, synchronize] - issue_comment: - types: [created] - -jobs: - auto-review: - if: github.event_name == 'pull_request' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: OpenHands PR Review - uses: openhands/review-action@v1 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - - issue-triage: - if: github.event_name == 'issues' && contains(github.event.issue.labels.*.name, 'needs-analysis') - runs-on: ubuntu-latest - steps: - - uses: openhands/triage-action@v1 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} -``` - -**Automated PR checks:** -- Code review on every PR -- Test coverage verification -- Security scanning -- Documentation checks - -### GitLab CI Integration - -```yaml -# .gitlab-ci.yml -stages: - - review - - test - - deploy - -openhands-review: - stage: review - script: - - openhands review --format gitlab - rules: - - if: $CI_PIPELINE_SOURCE == "merge_request_event" - -openhands-test-generation: - stage: test - script: - - openhands generate-tests --coverage-target 80 - artifacts: - reports: - coverage_report: - coverage_format: cobertura - path: coverage.xml -``` - -### Jenkins Integration - -```groovy -// Jenkinsfile -pipeline { - agent any - - stages { - stage('OpenHands Analysis') { - steps { - script { - sh 'openhands analyze --output analysis.json' - } - } - } - - stage('Review') { - when { - changeRequest() - } - steps { - script { - sh 'openhands review --format jenkins' - } - } - } - } - - post { - always { - archiveArtifacts artifacts: 'analysis.json' - } - } -} -``` - -### Other CI/CD Platforms - -**CircleCI:** -```yaml -version: 2.1 -jobs: - openhands-review: - docker: - - image: openhands/cli:latest - steps: - - checkout - - run: - name: Run OpenHands Review - command: openhands review --format circleci -``` - -**Azure DevOps:** -```yaml -trigger: - - main - -pool: - vmImage: 'ubuntu-latest' - -steps: - - task: Bash@3 - inputs: - targetType: 'inline' - script: | - openhands review --format azure -``` - -## Team Workflows - -### Solo Developer Workflows - -For individual developers: - -**Daily workflow:** -1. **Morning review**: Have OpenHands analyze overnight CI results -2. **Feature development**: Use OpenHands for implementation -3. **Pre-commit**: Request review before pushing -4. **Documentation**: Generate/update docs for changes - -**Best practices:** -- Set up automated reviews on all PRs -- Use OpenHands for boilerplate and repetitive tasks -- Keep AGENTS.md updated with project patterns - -### Small Team Workflows - -For teams of 2-10 developers: - -**Collaborative workflow:** -``` -Team Member A: Creates feature branch, writes initial implementation -OpenHands: Reviews code, suggests improvements -Team Member B: Reviews OpenHands suggestions, approves or modifies -OpenHands: Updates documentation, adds missing tests -Team: Merges after final human review -``` - -**Communication integration:** -- Slack notifications for OpenHands findings -- Automatic issue creation for bugs found -- Weekly summary reports - -### Enterprise Team Workflows - -For larger organizations: - -**Governance and oversight:** -- Configure approval requirements for OpenHands changes -- Set up audit logging for all AI-assisted changes -- Define scope limits for automated actions -- Establish human review requirements - -**Scale patterns:** -``` -Central Platform Team: -├── Defines OpenHands policies -├── Manages integrations -└── Monitors usage and quality - -Feature Teams: -├── Use OpenHands within policies -├── Customize for team needs -└── Report issues to platform team -``` - -## Best Practices - -### Code Review Integration - -Set up effective automated reviews: - -```yaml -# .openhands/review-config.yml -review: - focus_areas: - - security - - performance - - test_coverage - - documentation - - severity_levels: - block_merge: - - critical - - security - require_response: - - major - informational: - - minor - - suggestion - - ignore_patterns: - - "*.generated.*" - - "vendor/*" -``` - -### Pull Request Automation - -Automate common PR tasks: - -| Trigger | Action | -|---------|--------| -| PR opened | Auto-review, label by type | -| Tests fail | Analyze failures, suggest fixes | -| Coverage drops | Identify missing tests | -| PR approved | Update changelog, check docs | - -### Quality Gates - -Define automated quality gates: - -```yaml -quality_gates: - - name: test_coverage - threshold: 80% - action: block_merge - - - name: security_issues - threshold: 0 critical - action: block_merge - - - name: code_review_score - threshold: 7/10 - action: require_review - - - name: documentation - requirement: all_public_apis - action: warn -``` - -### Automated Testing - -Integrate OpenHands with your testing strategy: - -**Test generation triggers:** -- New code without tests -- Coverage below threshold -- Bug fix without regression test -- API changes without contract tests - -**Example workflow:** -```yaml -on: - push: - branches: [main] - -jobs: - ensure-coverage: - steps: - - name: Check coverage - run: | - COVERAGE=$(npm test -- --coverage | grep "All files" | awk '{print $10}') - if [ "$COVERAGE" -lt "80" ]; then - openhands generate-tests --target 80 - fi -``` - -## Common Integration Patterns - -### Pre-Commit Hooks - -Run OpenHands checks before commits: - -```bash -# .git/hooks/pre-commit -#!/bin/bash - -# Quick code review -openhands review --quick --staged-only - -if [ $? -ne 0 ]; then - echo "OpenHands found issues. Review and fix before committing." - exit 1 -fi -``` - -### Post-Commit Actions - -Automate tasks after commits: - -```yaml -# .github/workflows/post-commit.yml -on: - push: - branches: [main] - -jobs: - update-docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Update API docs - run: openhands update-docs --api - - name: Commit changes - run: | - git add docs/ - git commit -m "docs: auto-update API documentation" || true - git push -``` - -### Scheduled Tasks - -Run regular maintenance: - -```yaml -# Weekly dependency check -on: - schedule: - - cron: '0 9 * * 1' # Monday 9am - -jobs: - dependency-review: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Check dependencies - run: | - openhands check-dependencies --security --outdated - - name: Create issues - run: openhands create-issues --from-report deps.json -``` - -### Event-Triggered Workflows - -Respond to specific events: - -```yaml -# Respond to new issues -on: - issues: - types: [opened] - -jobs: - triage: - if: contains(github.event.issue.labels.*.name, 'bug') - runs-on: ubuntu-latest - steps: - - name: Analyze bug report - uses: openhands/triage-action@v1 - with: - action: | - Analyze this bug report and: - 1. Identify likely affected code - 2. Suggest reproduction steps - 3. Estimate severity - 4. Recommend assignee based on code ownership -``` - - -Start with simple integrations and expand as your team becomes comfortable. Not every workflow needs automation—focus on high-impact, repetitive tasks first. - diff --git a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx deleted file mode 100644 index 69816d66..00000000 --- a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: TODO-When to Use OpenHands -description: Guidance on when OpenHands is the right tool for your task ---- - -OpenHands excels at many development tasks, but knowing when to use it—and when to handle things yourself—helps you get the best results. This guide helps you identify the right tasks for OpenHands and set yourself up for success. - -## Task Complexity Guidance - -### Simple Tasks - -**Ideal for OpenHands** — These tasks can often be completed in a single session with minimal guidance. - -- Adding a new function or method -- Writing unit tests for existing code -- Fixing simple bugs with clear error messages -- Code formatting and style fixes -- Adding documentation or comments -- Simple refactoring (rename, extract method) -- Configuration changes - -**Example prompt:** -``` -Add a calculateDiscount() function to src/utils/pricing.js that takes -a price and discount percentage, returns the discounted price. -Add unit tests. -``` - -### Medium Complexity Tasks - -**Good for OpenHands** — These tasks may need more context and possibly some iteration. - -- Implementing a new API endpoint -- Adding a feature to an existing module -- Debugging issues that span multiple files -- Migrating code to a new pattern -- Writing integration tests -- Performance optimization with clear metrics -- Setting up CI/CD workflows - -**Example prompt:** -``` -Add a user profile endpoint to our API: -- GET /api/users/:id/profile -- Return user data with their recent activity -- Follow patterns in existing controllers -- Add integration tests -- Handle not-found and unauthorized cases -``` - -### Complex Tasks - -**May require iteration** — These benefit from breaking down into smaller pieces. - -- Large refactoring across many files -- Architectural changes -- Implementing complex business logic -- Multi-service integrations -- Performance optimization without clear cause -- Security audits -- Framework or major dependency upgrades - -**Recommended approach:** -``` -Break large tasks into phases: - -Phase 1: "Analyze the current authentication system and document -all touch points that need to change for OAuth2 migration." - -Phase 2: "Implement the OAuth2 provider configuration and basic -token flow, keeping existing auth working in parallel." - -Phase 3: "Migrate the user login flow to use OAuth2, maintaining -backwards compatibility." -``` - -## Best Use Cases - -### Ideal Scenarios - -OpenHands is **most effective** when: - -| Scenario | Why It Works | -|----------|--------------| -| Clear requirements | OpenHands can work independently | -| Well-defined scope | Less ambiguity, fewer iterations | -| Existing patterns to follow | Consistency with codebase | -| Good test coverage | Easy to verify changes | -| Isolated changes | Lower risk of side effects | - -**Perfect use cases:** - -- **Bug fixes with reproduction steps**: Clear problem, measurable solution -- **Test additions**: Existing code provides the specification -- **Documentation**: Code is the source of truth -- **Boilerplate generation**: Follows established patterns -- **Code review and analysis**: Read-only, analytical tasks - -### Good Fit Scenarios - -OpenHands works **well with some guidance** for: - -- **Feature implementation**: When requirements are documented -- **Refactoring**: When goals and constraints are clear -- **Debugging**: When you can provide logs and context -- **Code modernization**: When patterns are established -- **API development**: When specs exist - -**Tips for these scenarios:** - -1. Provide clear acceptance criteria -2. Point to examples of similar work in the codebase -3. Specify constraints and non-goals -4. Be ready to iterate and clarify - -### Poor Fit Scenarios - -**Consider alternatives** when: - -| Scenario | Challenge | Alternative | -|----------|-----------|-------------| -| Vague requirements | Unclear what "done" means | Define requirements first | -| Exploratory work | Need human creativity/intuition | Brainstorm first, then implement | -| Highly sensitive code | Risk tolerance is zero | Human review essential | -| Organizational knowledge | Needs tribal knowledge | Pair with domain expert | -| Visual design | Subjective aesthetic judgments | Use design tools | - -**Red flags that a task may not be suitable:** - -- "Make it look better" (subjective) -- "Figure out what's wrong" (too vague) -- "Rewrite everything" (too large) -- "Do what makes sense" (unclear requirements) -- Changes to production infrastructure without review - -## Limitations - -### Current Limitations - -Be aware of these constraints: - -- **Long-running processes**: Sessions have time limits -- **Interactive debugging**: Can't set breakpoints interactively -- **Visual verification**: Can't see rendered UI easily -- **External system access**: May need credentials configured -- **Large codebase analysis**: Memory and time constraints - -### Technical Constraints - -| Constraint | Impact | Workaround | -|------------|--------|------------| -| Session duration | Very long tasks may timeout | Break into smaller tasks | -| Context window | Can't see entire large codebase at once | Focus on relevant files | -| No persistent state | Previous sessions not remembered | Use AGENTS.md for context | -| Network access | Some external services may be blocked | Use local resources when possible | - -### Scope Boundaries - -OpenHands works within your codebase but has boundaries: - -**Can do:** -- Read and write files in the repository -- Run tests and commands -- Access configured services and APIs -- Browse documentation and reference material - -**Cannot do:** -- Access your local environment outside the sandbox -- Make decisions requiring business context it doesn't have -- Replace human judgment for critical decisions -- Guarantee production-safe changes without review - -## Pre-Task Checklist - -### Prerequisites - -Before starting a task, ensure: - -- [ ] Clear description of what you want -- [ ] Expected outcome is defined -- [ ] Relevant files are identified -- [ ] Dependencies are available -- [ ] Tests can be run - -### Environment Setup - -Prepare your repository: - -```markdown -## AGENTS.md Checklist - -- [ ] Build commands documented -- [ ] Test commands documented -- [ ] Code style guidelines noted -- [ ] Architecture overview included -- [ ] Common patterns described -``` - -See [Repository Setup](/openhands/usage/customization/repository) for details. - -### Repository Preparation - -Optimize for success: - -1. **Clean state**: Commit or stash uncommitted changes -2. **Working build**: Ensure the project builds -3. **Passing tests**: Start from a green state -4. **Updated dependencies**: Resolve any dependency issues -5. **Clear documentation**: Update AGENTS.md if needed - -## Post-Task Review - -### Quality Checks - -After OpenHands completes a task: - -- [ ] Review all changed files -- [ ] Understand each change made -- [ ] Check for unintended modifications -- [ ] Verify code style consistency -- [ ] Look for hardcoded values or credentials - -### Validation Steps - -1. **Run tests**: `npm test`, `pytest`, etc. -2. **Check linting**: Ensure style compliance -3. **Build the project**: Verify it still compiles -4. **Manual testing**: Test the feature yourself -5. **Edge cases**: Try unusual inputs - -### Learning from Results - -After each significant task: - -**What went well?** -- Note effective prompt patterns -- Document successful approaches -- Update AGENTS.md with learnings - -**What could improve?** -- Identify unclear instructions -- Note missing context -- Plan better for next time - -**Update your repository:** -```markdown -## Things OpenHands Should Know (add to AGENTS.md) - -- When adding API endpoints, always add to routes/index.js -- Our date format is ISO 8601 everywhere -- All database queries go through the repository pattern -``` - -## Decision Framework - -Use this framework to decide if a task is right for OpenHands: - -``` -Is the task well-defined? -├── No → Define it better first -└── Yes → Continue - -Do you have clear success criteria? -├── No → Define acceptance criteria -└── Yes → Continue - -Is the scope manageable (< 100 LOC)? -├── No → Break into smaller tasks -└── Yes → Continue - -Do examples exist in the codebase? -├── No → Provide examples or patterns -└── Yes → Continue - -Can you verify the result? -├── No → Add tests or verification steps -└── Yes → ✅ Good candidate for OpenHands -``` - - -When in doubt, start small. A focused task that succeeds builds confidence for larger tasks. You can always iterate and expand scope based on results. - diff --git a/openhands/usage/get-started/tutorials.mdx b/openhands/usage/get-started/tutorials.mdx deleted file mode 100644 index 8e14fd52..00000000 --- a/openhands/usage/get-started/tutorials.mdx +++ /dev/null @@ -1,438 +0,0 @@ ---- -title: Tutorial Library -description: Centralized hub for OpenHands tutorials and examples ---- - -Welcome to the OpenHands tutorial library. These tutorials show you how to use OpenHands for common development tasks, from testing to feature development. Each tutorial includes example prompts, expected workflows, and tips for success. - -## Categories Overview - -| Category | Best For | Complexity | -|----------|----------|------------| -| [Testing](#testing) | Adding tests, improving coverage | Simple to Medium | -| [Data Analysis](#data-analysis) | Processing data, generating reports | Simple to Medium | -| [Web Scraping](#web-scraping) | Extracting data from websites | Medium | -| [Code Review](#code-review) | Analyzing PRs, finding issues | Simple | -| [Bug Fixing](#bug-fixing) | Diagnosing and fixing errors | Medium | -| [Feature Development](#feature-development) | Building new functionality | Medium to Complex | - - -For in-depth guidance on specific use cases, see our [Use Cases](/openhands/usage/use-cases/code-review) section which includes detailed workflows for Code Review, Incident Triage, and more. - - -## Task Complexity Guidance - -Before starting, assess your task's complexity: - -**Simple tasks** (5-15 minutes): -- Single file changes -- Clear, well-defined requirements -- Existing patterns to follow - -**Medium tasks** (15-45 minutes): -- Multiple file changes -- Some discovery required -- Integration with existing code - -**Complex tasks** (45+ minutes): -- Architectural changes -- Multiple components -- Requires iteration - - -Start with simpler tutorials to build familiarity with OpenHands before tackling complex tasks. - - -## Best Use Cases - -OpenHands excels at: - -- **Repetitive tasks**: Boilerplate code, test generation -- **Pattern application**: Following established conventions -- **Analysis**: Code review, debugging, documentation -- **Exploration**: Understanding new codebases - -## Example Tutorials by Category - -### Testing - -#### Tutorial: Add Unit Tests for a Module - -**Goal**: Achieve 80%+ test coverage for a service module - -**Prompt**: -``` -Add unit tests for the UserService class in src/services/user.js. - -Current coverage: 35% -Target coverage: 80% - -Requirements: -1. Test all public methods -2. Cover edge cases (null inputs, empty arrays, etc.) -3. Mock external dependencies (database, API calls) -4. Follow our existing test patterns in tests/services/ -5. Use Jest as the testing framework - -Focus on these methods: -- createUser() -- updateUser() -- deleteUser() -- getUserById() -``` - -**What OpenHands does**: -1. Analyzes the UserService class -2. Identifies untested code paths -3. Creates test file with comprehensive tests -4. Mocks dependencies appropriately -5. Runs tests to verify they pass - -**Tips**: -- Provide existing test files as examples -- Specify the testing framework -- Mention any mocking conventions - ---- - -#### Tutorial: Add Integration Tests for an API - -**Goal**: Test API endpoints end-to-end - -**Prompt**: -``` -Add integration tests for the /api/products endpoints. - -Endpoints to test: -- GET /api/products (list all) -- GET /api/products/:id (get one) -- POST /api/products (create) -- PUT /api/products/:id (update) -- DELETE /api/products/:id (delete) - -Requirements: -1. Use our test database (configured in jest.config.js) -2. Set up and tear down test data properly -3. Test success cases and error cases -4. Verify response bodies and status codes -5. Follow patterns in tests/integration/ -``` - ---- - -### Data Analysis - -#### Tutorial: Create a Data Processing Script - -**Goal**: Process CSV data and generate a report - -**Prompt**: -``` -Create a Python script to analyze our sales data. - -Input: sales_data.csv with columns: date, product, quantity, price, region - -Requirements: -1. Load and validate the CSV data -2. Calculate: - - Total revenue by product - - Monthly sales trends - - Top 5 products by quantity - - Revenue by region -3. Generate a summary report (Markdown format) -4. Create visualizations (bar chart for top products, line chart for trends) -5. Save results to reports/ directory - -Use pandas for data processing and matplotlib for charts. -``` - -**What OpenHands does**: -1. Creates a Python script with proper structure -2. Implements data loading with validation -3. Calculates requested metrics -4. Generates formatted report -5. Creates and saves visualizations - ---- - -#### Tutorial: Database Query Analysis - -**Goal**: Analyze and optimize slow database queries - -**Prompt**: -``` -Analyze our slow query log and identify optimization opportunities. - -File: logs/slow_queries.log - -For each slow query: -1. Explain why it's slow -2. Suggest index additions if helpful -3. Rewrite the query if it can be optimized -4. Estimate the improvement - -Create a report in reports/query_optimization.md with: -- Summary of findings -- Prioritized recommendations -- SQL for suggested changes -``` - ---- - -### Web Scraping - -#### Tutorial: Build a Web Scraper - -**Goal**: Extract product data from a website - -**Prompt**: -``` -Create a web scraper to extract product information from our competitor's site. - -Target URL: https://example-store.com/products - -Extract for each product: -- Name -- Price -- Description -- Image URL -- SKU (if available) - -Requirements: -1. Use Python with BeautifulSoup or Scrapy -2. Handle pagination (site has 50 pages) -3. Respect rate limits (1 request/second) -4. Save results to products.json -5. Handle errors gracefully -6. Log progress to console - -Include a README with usage instructions. -``` - -**Tips**: -- Specify rate limiting requirements -- Mention error handling expectations -- Request logging for debugging - ---- - -### Code Review - - -For comprehensive code review guidance, see the [Code Review Use Case](/openhands/usage/use-cases/code-review) page. For automated PR reviews using GitHub Actions, see the [PR Review SDK Guide](/sdk/guides/github-workflows/pr-review). - - -#### Tutorial: Security-Focused Code Review - -**Goal**: Identify security vulnerabilities in a PR - -**Prompt**: -``` -Review this pull request for security issues: - -Focus areas: -1. Input validation - check all user inputs are sanitized -2. Authentication - verify auth checks are in place -3. SQL injection - check for parameterized queries -4. XSS - verify output encoding -5. Sensitive data - ensure no secrets in code - -For each issue found, provide: -- File and line number -- Severity (Critical/High/Medium/Low) -- Description of the vulnerability -- Suggested fix with code example - -Output format: Markdown suitable for PR comments -``` - ---- - -#### Tutorial: Performance Review - -**Goal**: Identify performance issues in code - -**Prompt**: -``` -Review the OrderService class for performance issues. - -File: src/services/order.js - -Check for: -1. N+1 database queries -2. Missing indexes (based on query patterns) -3. Inefficient loops or algorithms -4. Missing caching opportunities -5. Unnecessary data fetching - -For each issue: -- Explain the impact -- Show the problematic code -- Provide an optimized version -- Estimate the improvement -``` - ---- - -### Bug Fixing - - -For production incident investigation and automated error analysis, see the [Incident Triage Use Case](/openhands/usage/use-cases/incident-triage) which covers integration with monitoring tools like Datadog. - - -#### Tutorial: Fix a Crash Bug - -**Goal**: Diagnose and fix an application crash - -**Prompt**: -``` -Fix the crash in the checkout process. - -Error: -TypeError: Cannot read property 'price' of undefined - at calculateTotal (src/checkout/calculator.js:45) - at processOrder (src/checkout/processor.js:23) - -Steps to reproduce: -1. Add item to cart -2. Apply discount code "SAVE20" -3. Click checkout -4. Crash occurs - -The bug was introduced in commit abc123 (yesterday's deployment). - -Requirements: -1. Identify the root cause -2. Fix the bug -3. Add a regression test -4. Verify the fix doesn't break other functionality -``` - -**What OpenHands does**: -1. Analyzes the stack trace -2. Reviews recent changes -3. Identifies the null reference issue -4. Implements a defensive fix -5. Creates test to prevent regression - ---- - -#### Tutorial: Fix a Memory Leak - -**Goal**: Identify and fix a memory leak - -**Prompt**: -``` -Investigate and fix the memory leak in our Node.js application. - -Symptoms: -- Memory usage grows 100MB/hour -- After 24 hours, app becomes unresponsive -- Restarting temporarily fixes the issue - -Suspected areas: -- Event listeners in src/events/ -- Cache implementation in src/cache/ -- WebSocket connections in src/ws/ - -Analyze these areas and: -1. Identify the leak source -2. Explain why it's leaking -3. Implement a fix -4. Add monitoring to detect future leaks -``` - ---- - -### Feature Development - -#### Tutorial: Add a REST API Endpoint - -**Goal**: Create a new API endpoint with full functionality - -**Prompt**: -``` -Add a user preferences API endpoint. - -Endpoint: /api/users/:id/preferences - -Operations: -- GET: Retrieve user preferences -- PUT: Update user preferences -- PATCH: Partially update preferences - -Preferences schema: -{ - theme: "light" | "dark", - notifications: { email: boolean, push: boolean }, - language: string, - timezone: string -} - -Requirements: -1. Follow patterns in src/api/routes/ -2. Add request validation with Joi -3. Use UserPreferencesService for business logic -4. Add appropriate error handling -5. Document the endpoint in OpenAPI format -6. Add unit and integration tests -``` - -**What OpenHands does**: -1. Creates route handler following existing patterns -2. Implements validation middleware -3. Creates or updates the service layer -4. Adds error handling -5. Generates API documentation -6. Creates comprehensive tests - ---- - -#### Tutorial: Implement a Feature Flag System - -**Goal**: Add feature flags to the application - -**Prompt**: -``` -Implement a feature flag system for our application. - -Requirements: -1. Create a FeatureFlags service -2. Support these flag types: - - Boolean (on/off) - - Percentage (gradual rollout) - - User-based (specific user IDs) -3. Load flags from environment variables initially -4. Add a React hook: useFeatureFlag(flagName) -5. Add middleware for API routes - -Initial flags to configure: -- new_checkout: boolean, default false -- dark_mode: percentage, default 10% -- beta_features: user-based - -Include documentation and tests. -``` - ---- - -## Contributing Tutorials - -Have a great use case? Share it with the community! - -**What makes a good tutorial:** -- Solves a common problem -- Has clear, reproducible steps -- Includes example prompts -- Explains expected outcomes -- Provides tips for success - -**How to contribute:** -1. Create a detailed example following this format -2. Test it with OpenHands to verify it works -3. Submit via GitHub pull request to the docs repository -4. Include any prerequisites or setup required - - -These tutorials are starting points. The best results come from adapting them to your specific codebase, conventions, and requirements. - diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx deleted file mode 100644 index 4044465d..00000000 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: COBOL Modernization -description: Modernizing legacy COBOL systems with OpenHands ---- - -Legacy COBOL systems power critical business operations across banking, insurance, government, and retail. OpenHands can help you understand, document, and modernize these systems while preserving their essential business logic. - - -This guide is based on our blog post [Refactoring COBOL to Java with AI Agents](https://openhands.dev/blog/20251218-cobol-to-java-refactoring). - - -## The COBOL Modernization Challenge - -[COBOL](https://en.wikipedia.org/wiki/COBOL) modernization is one of the most pressing challenges facing enterprises today. Gartner estimated there were over 200 billion lines of COBOL code in existence, running 80% of the world's business systems. As of 2020, COBOL was still running background processes for 95% of credit and debit card transactions. - -The challenge is acute: [47% of organizations](https://softwaremodernizationservices.com/mainframe-modernization) struggle to fill COBOL roles, with salaries rising 25% annually. By 2027, 92% of remaining COBOL developers will have retired. Traditional modernization approaches have seen high failure rates, with COBOL's specialized nature requiring a unique skill set that makes it difficult for human teams alone. - -## Overview - -COBOL modernization is a complex undertaking. Every modernization effort is unique and requires careful planning, execution, and validation to ensure the modernized code behaves identically to the original. The migration needs to be driven by an experienced team of developers and domain experts, but even that isn't sufficient to ensure the job is done quickly or cost-effectively. This is where OpenHands comes in. - -OpenHands is a powerful agent that assists in modernizing COBOL code along every step of the process: - -1. **Understanding**: Analyze and document existing COBOL code -2. **Translation**: Convert COBOL to modern languages like Java, Python, or C# -3. **Validation**: Ensure the modernized code behaves identically to the original - -In this document, we will explore the different ways OpenHands contributes to COBOL modernization, with example prompts and techniques to use in your own efforts. While the examples are specific to COBOL, the principles laid out here can help with any legacy system modernization. - -## Understanding - -A significant challenge in modernization is understanding the business function of the code. Developers have practice determining the "how" of the code, even in legacy systems with unfamiliar syntax and keywords, but understanding the "why" is more important to ensure that business logic is preserved accurately. The difficulty then comes from the fact that business function is only implicitly represented in the code and requires external documentation or domain expertise to untangle. - -Fortunately, agents like OpenHands are able to understand source code _and_ process-oriented documentation, and this simultaneous view lets them link the two together in a way that makes every downstream process more transparent and predictable. Your COBOL source might already have some structure or comments that make this link clear, but if not OpenHands can help. If your COBOL source is in `/src` and your process-oriented documentation is in `/docs`, the following prompt will establish a link between the two and save it for future reference: - -``` -For each COBOL program in `/src`, identify which business functions it supports. Search through the documentation in `/docs` to find all relevant sections describing that business function, and generate a summary of how the program supports that function. - -Save the results in `business_functions.json` in the following format: - -{ - ..., - "COBIL00C.cbl": { - "function": "Bill payment -- pay account balance in full and a transaction action for the online payment", - "references": [ - "docs/billing.md#bill-payment", - "docs/transactions.md#transaction-action" - ], - }, - ... -} -``` - -OpenHands uses tools like `grep`, `sed`, and `awk` to navigate files and pull in context. This is natural for source code and also works well for process-oriented documentation, but in some cases exposing the latter using a _semantic search engine_ instead will yield better results. Semantic search engines can understand the meaning behind words and phrases, making it easier to find relevant information. - -## Translation - -With a clear picture of what each program does and why, the next step is translating the COBOL source into your target language. The example prompts in this section target Java, but the same approach works for Python, C#, or any modern language. Just adjust for language-specific idioms and data types as needed. - -One thing to watch out for: COBOL keywords and data types do not always match one-to-one with their Java counterparts. For example, COBOL's decimal data type (`PIC S9(9)V9(9)`), which represents a fixed-point number with a scale of 9 digits, does not have a direct equivalent in Java. Instead, you might use `BigDecimal` with a scale of 9, but be aware of potential precision issues when converting between the two. A solid test suite will help catch these corner cases but including such _known problems_ in the translation prompt can help prevent such errors from being introduced at all. - -An example prompt is below: - -``` -Convert the COBOL files in `/src` to Java in `/src/java`. - -Requirements: -1. Create a Java class for each COBOL program -2. Preserve the business logic and data structures (see `business_functions.json`) -3. Use appropriate Java naming conventions (camelCase for methods, PascalCase) -4. Convert COBOL data types to appropriate Java types (use BigDecimal for decimal data types) -5. Implement proper error handling with try-catch blocks -6. Add JavaDoc comments explaining the purpose of each class and method -7. In JavaDoc comments, include traceability to the original COBOL source using - the format: @source : (e.g., @source CBACT01C.cbl:73-77) -8. Create a clean, maintainable object-oriented design -9. Each Java file should be compilable and follow Java best practices -``` - -Note the rule that introduces traceability comments to the resulting Java. These comments help agents understand the provenance of the code, but are also helpful for developers attempting to understand the migration process. They can be used, for example, to check how much COBOL code has been translated into Java or to identify areas where business logic has been distributed across multiple Java classes. - -## Validation - -Building confidence in the migrated code is crucial. Ideally, existing end-to-end tests can be reused to validate that business logic has been preserved. If you need to strengthen the testing setup, consider _golden file testing_. This involves capturing the COBOL program's outputs for a set of known inputs, then verifying the translated code produces identical results. When generating inputs, pay particular attention to decimal precision in monetary calculations (COBOL's fixed-point arithmetic doesn't always map cleanly to Java's BigDecimal) and date handling, where COBOL's conventions can diverge from modern defaults. - -Every modernization effort is unique, and developer experience is crucial to ensure the testing strategy covers your organization's requirements. Best practices still apply. A solid test suite will not only ensure the migrated code works as expected, but will also help the translation agent converge to a high-quality solution. Of course, OpenHands can help migrate tests, ensure they run and test the migrated code correctly, and even generate new tests to cover edge cases. - -## Scaling Up - -The largest challenge in scaling modernization efforts is dealing with agents' limited attention span. Asking a single agent to handle the entire migration process in one go will almost certainly lead to errors and low-quality code as the context window is filled and flushed again and again. One way to address this is by tying translation and validation together in an iterative refinement loop. - -The idea is straightforward: one agent migrates some amount of code, and another agent critiques the migration. If the quality doesn't meet the standards of the critic, the first agent is given some actionable feedback and the process repeats. Here's what that looks like using the [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk): - -```python -while current_score < QUALITY_THRESHOLD and iteration < MAX_ITERATIONS: - # Migrating agent converts COBOL to Java - migration_conversation.send_message(migration_prompt) - migration_conversation.run() - - # Critiquing agent evaluates the conversion - critique_conversation.send_message(critique_prompt) - critique_conversation.run() - - # Parse the score and decide whether to continue - current_score = parse_critique_score(critique_file) -``` - -By tweaking the critic's prompt and scoring rubric, you can fine-tune the evaluation process to better align with your needs. For example, you might have code quality standards that are difficult to detect with static analysis tools or architectural patterns that are unique to your organization. The following prompt can be easily modified to support a wide range of requirements: - -``` -Evaluate the quality of the COBOL to Java migration in `/src`. - -For each Java file, assess using the following criteria: -1. Correctness: Does the Java code preserve the original business logic (see `business_functions.json`)? -2. Code Quality: Is the code clean, readable, and following Java 17 conventions? -3. Completeness: Are all COBOL features properly converted? -4. Best Practices: Does it use proper OOP, error handling, and documentation? - -For each instance of a criteria not met, deduct a point. - -Then generate a report containing actionable feedback for each file. The feedback, if addressed, should improve the score. - -Save the results in `critique.json` in the following format: - -{ - "total_score": -12, - "files": [ - { - "cobol": "COBIL00C.cbl", - "java": "bill_payment.java", - "scores": { - "correctness": 0, - "code_quality": 0, - "completeness": -1, - "best_practices": -2 - }, - "feedback": [ - "Rename single-letter variables to meaningful names.", - "Ensure all COBOL functionality is translated -- the transaction action for the bill payment is missing.", - ], - }, - ... - ] -} -``` - -In future iterations, the migration agent should be given the file `critique.json` and be prompted to act on the feedback. - -This iterative refinement pattern works well for medium-sized projects with a moderate level of complexity. For legacy systems that span hundreds of files, however, the migration and critique processes need to be further decomposed to prevent agents from being overwhelmed. A natural way to do so is to break the system into smaller components, each with its own migration and critique processes. This process can be automated by using the OpenHands large codebase SDK, which combines agentic intelligence with static analysis tools to decompose large projects and orchestrate parallel agents in a dependency-aware manner. - -## Try It Yourself - -The full iterative refinement example is available in the OpenHands SDK: - -```bash -export LLM_API_KEY="your-api-key" -cd software-agent-sdk -uv run python examples/01_standalone_sdk/31_iterative_refinement.py -``` - -For real-world COBOL files, you can use the [AWS CardDemo application](https://github.com/aws-samples/aws-mainframe-modernization-carddemo/tree/main/app/cbl), which provides a representative mainframe application for testing modernization approaches. - - -## Related Resources - -- [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents -- [AWS CardDemo Application](https://github.com/aws-samples/aws-mainframe-modernization-carddemo/tree/main/app/cbl) - Sample COBOL application for testing -- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx deleted file mode 100644 index aa6c219a..00000000 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ /dev/null @@ -1,384 +0,0 @@ ---- -title: Dependency Upgrades -description: Automating dependency updates and upgrades with OpenHands ---- - -Keeping dependencies up to date is essential for security, performance, and access to new features. OpenHands can help you identify outdated dependencies, plan upgrades, handle breaking changes, and validate that your application still works after updates. - -## Overview - -OpenHands helps with dependency management by: - -- **Analyzing dependencies**: Identifying outdated packages and their versions -- **Planning upgrades**: Creating upgrade strategies and migration guides -- **Implementing changes**: Updating code to handle breaking changes -- **Validating results**: Running tests and verifying functionality - -## Dependency Analysis - -### Identifying Outdated Dependencies - -Start by understanding your current dependency state: - -``` -Analyze the dependencies in this project and create a report: - -1. List all direct dependencies with current and latest versions -2. Identify dependencies more than 2 major versions behind -3. Flag any dependencies with known security vulnerabilities -4. Highlight dependencies that are deprecated or unmaintained -5. Prioritize which updates are most important -``` - -**Example output:** - -| Package | Current | Latest | Risk | Priority | -|---------|---------|--------|------|----------| -| lodash | 4.17.15 | 4.17.21 | Security (CVE) | High | -| react | 16.8.0 | 18.2.0 | Outdated | Medium | -| express | 4.17.1 | 4.18.2 | Minor update | Low | -| moment | 2.29.1 | 2.29.4 | Deprecated | Medium | - -### Security-Related Dependency Upgrades - -Dependency upgrades are often needed to fix security vulnerabilities in your dependencies. If you're upgrading dependencies specifically to address security issues, see our [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) guide for comprehensive guidance on: - -- Automating vulnerability detection and remediation -- Integrating with security scanners (Snyk, Dependabot, CodeQL) -- Building automated pipelines for security fixes -- Using OpenHands agents to create pull requests automatically - -### Compatibility Checking - -Check for compatibility issues before upgrading: - -``` -Check compatibility for upgrading React from 16 to 18: - -1. Review our codebase for deprecated React patterns -2. List all components using lifecycle methods -3. Identify usage of string refs or findDOMNode -4. Check third-party library compatibility with React 18 -5. Estimate the effort required for migration -``` - -**Compatibility matrix:** - -| Dependency | React 16 | React 17 | React 18 | Action Needed | -|------------|----------|----------|----------|---------------| -| react-router | v5 ✓ | v5 ✓ | v6 required | Major upgrade | -| styled-components | v5 ✓ | v5 ✓ | v5 ✓ | None | -| material-ui | v4 ✓ | v4 ✓ | v5 required | Major upgrade | - -## Automated Upgrades - -### Version Updates - -Perform straightforward version updates: - - - - ``` - Update all patch and minor versions in package.json: - - 1. Review each update for changelog notes - 2. Update package.json with new versions - 3. Update package-lock.json - 4. Run the test suite - 5. List any deprecation warnings - ``` - - - ``` - Update dependencies in requirements.txt: - - 1. Check each package for updates - 2. Update requirements.txt with compatible versions - 3. Update requirements-dev.txt similarly - 4. Run tests and verify functionality - 5. Note any deprecation warnings - ``` - - - ``` - Update dependencies in pom.xml: - - 1. Check for newer versions of each dependency - 2. Update version numbers in pom.xml - 3. Run mvn dependency:tree to check conflicts - 4. Run the test suite - 5. Document any API changes encountered - ``` - - - -### Breaking Change Handling - -When major versions introduce breaking changes: - -``` -Upgrade axios from v0.x to v1.x and handle breaking changes: - -1. List all breaking changes in axios 1.0 changelog -2. Find all axios usages in our codebase -3. For each breaking change: - - Show current code - - Show updated code - - Explain the change -4. Create a git commit for each logical change -5. Verify all tests pass -``` - -**Example transformation:** - -```javascript -// Before (axios 0.x) -import axios from 'axios'; -axios.defaults.baseURL = 'https://api.example.com'; -const response = await axios.get('/users', { - cancelToken: source.token -}); - -// After (axios 1.x) -import axios from 'axios'; -axios.defaults.baseURL = 'https://api.example.com'; -const controller = new AbortController(); -const response = await axios.get('/users', { - signal: controller.signal -}); -``` - -### Code Adaptation - -Adapt code to new API patterns: - -``` -Migrate our codebase from moment.js to date-fns: - -1. List all moment.js usages in our code -2. Map moment methods to date-fns equivalents -3. Update imports throughout the codebase -4. Handle any edge cases where APIs differ -5. Remove moment.js from dependencies -6. Verify all date handling still works correctly -``` - -**Migration map:** - -| moment.js | date-fns | Notes | -|-----------|----------|-------| -| `moment()` | `new Date()` | Different return type | -| `moment().format('YYYY-MM-DD')` | `format(new Date(), 'yyyy-MM-dd')` | Different format tokens | -| `moment().add(1, 'days')` | `addDays(new Date(), 1)` | Function-based API | -| `moment().startOf('month')` | `startOfMonth(new Date())` | Separate function | - -## Testing and Validation - -### Automated Test Execution - -Run comprehensive tests after upgrades: - -``` -After the dependency upgrades, validate the application: - -1. Run the full test suite (unit, integration, e2e) -2. Check test coverage hasn't decreased -3. Run type checking (if applicable) -4. Run linting with new lint rule versions -5. Build the application for production -6. Report any failures with analysis -``` - -### Integration Testing - -Verify integrations still work: - -``` -Test our integrations after upgrading the AWS SDK: - -1. Test S3 operations (upload, download, list) -2. Test DynamoDB operations (CRUD) -3. Test Lambda invocations -4. Test SQS send/receive -5. Compare behavior to before the upgrade -6. Note any subtle differences -``` - -### Regression Detection - -Detect regressions from upgrades: - -``` -Check for regressions after upgrading the ORM: - -1. Run database operation benchmarks -2. Compare query performance before and after -3. Verify all migrations still work -4. Check for any N+1 queries introduced -5. Validate data integrity in test database -6. Document any behavioral changes -``` - -## Upgrade Strategies - -### Conservative Approach - -For production-critical applications: - -``` -Create a conservative upgrade plan for our payment service: - -1. Only upgrade packages with security vulnerabilities -2. For each upgrade: - - Create a separate branch - - Run full test suite - - Deploy to staging - - Monitor for 1 week -3. Document rollback procedures -4. Schedule upgrades during low-traffic periods -``` - -### Progressive Approach - -For active development: - -``` -Create a progressive upgrade plan: - -1. Weekly: Update patch versions automatically -2. Monthly: Review and apply minor version updates -3. Quarterly: Plan and execute major version upgrades -4. Create automation for tracking new versions -5. Set up alerts for security advisories -``` - -### Big Bang Approach - -For major framework upgrades: - -``` -Plan a big-bang upgrade from Django 2.x to 4.x: - -1. Create a comprehensive upgrade branch -2. Address all deprecation warnings first -3. Make all breaking changes -4. Update all related packages -5. Extensive testing phase -6. Feature freeze during migration -7. Coordinated rollout with rollback plan -``` - -## Best Practices - -### Effective Upgrade Prompts - -Provide context for better upgrades: - -``` -Upgrade our Express.js application from v4 to v5: - -Project context: -- Production API with 50+ endpoints -- Uses express-validator, passport, helmet -- Custom middleware for logging and auth -- TypeScript with strict mode - -Requirements: -1. Maintain backwards compatibility with clients -2. No downtime during deployment -3. Keep all existing functionality -4. Update TypeScript types -``` - -### Upgrade Checklist - -Before upgrading: - -- [ ] Read the changelog and migration guide -- [ ] Check compatibility with other dependencies -- [ ] Review breaking changes -- [ ] Ensure test coverage is adequate -- [ ] Plan rollback strategy - -After upgrading: - -- [ ] Run full test suite -- [ ] Check for deprecation warnings -- [ ] Verify production build works -- [ ] Test in staging environment -- [ ] Monitor after production deployment - -### Common Pitfalls - - -Avoid these upgrade mistakes: - -- **Upgrading everything at once**: Change one thing at a time -- **Skipping changelogs**: Always read what changed -- **Ignoring deprecation warnings**: Fix them before they become errors -- **Insufficient testing**: Upgrade testing should be thorough -- **No rollback plan**: Always be able to revert - - -## Examples - -### Security-Driven Upgrade - -``` -We have a critical security vulnerability in jsonwebtoken. - -Current: jsonwebtoken@8.5.1 -Required: jsonwebtoken@9.0.0 - -Perform the upgrade: -1. Check for breaking changes in v9 -2. Find all usages of jsonwebtoken in our code -3. Update any deprecated methods -4. Update the package version -5. Verify all JWT operations work -6. Run security tests -``` - -### Framework Major Upgrade - -``` -Upgrade our Next.js application from 12 to 14: - -Key areas to address: -1. App Router migration (pages -> app) -2. New metadata API -3. Server Components by default -4. New Image component -5. Route handlers replacing API routes - -For each area: -- Show current implementation -- Show new implementation -- Test the changes -``` - -### Multi-Package Coordinated Upgrade - -``` -Upgrade our React ecosystem packages together: - -Current: -- react: 17.0.2 -- react-dom: 17.0.2 -- react-router-dom: 5.3.0 -- @testing-library/react: 12.1.2 - -Target: -- react: 18.2.0 -- react-dom: 18.2.0 -- react-router-dom: 6.x -- @testing-library/react: 14.x - -Create an upgrade plan that handles all these together, -addressing breaking changes in the correct order. -``` - -## Related Resources - -- [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities -- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx deleted file mode 100644 index a193aeb5..00000000 --- a/openhands/usage/use-cases/incident-triage.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Incident Triage -description: Using OpenHands to investigate and resolve production incidents ---- - -When production incidents occur, speed matters. OpenHands can help you quickly investigate issues, analyze logs and errors, identify root causes, and generate fixes—reducing your mean time to resolution (MTTR). - - -This guide is based on our blog post [Debugging Production Issues with AI Agents: Automating Datadog Error Analysis](https://openhands.dev/blog/debugging-production-issues-with-ai-agents-automating-datadog-error-analysis). - - -## Overview - -Running a production service is **hard**. Errors and bugs crop up due to product updates, infrastructure changes, or unexpected user behavior. When these issues arise, it's critical to identify and fix them quickly to minimize downtime and maintain user trust—but this is challenging, especially at scale. - -What if AI agents could handle the initial investigation automatically? This allows engineers to start with a detailed report of the issue, including root cause analysis and specific recommendations for fixes, dramatically speeding up the debugging process. - -OpenHands accelerates incident response by: - -- **Automated error analysis**: AI agents investigate errors and provide detailed reports -- **Root cause identification**: Connect symptoms to underlying issues in your codebase -- **Fix recommendations**: Generate specific, actionable recommendations for resolving issues -- **Integration with monitoring tools**: Work directly with platforms like Datadog - -## Automated Datadog Error Analysis - -The [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk) provides powerful capabilities for building autonomous AI agents that can integrate with monitoring platforms like Datadog. A ready-to-use [GitHub Actions workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) demonstrates how to automate error analysis. - -### How It Works - -[Datadog](https://www.datadoghq.com/) is a popular monitoring and analytics platform that provides comprehensive error tracking capabilities. It aggregates logs, metrics, and traces from your applications, making it easier to identify and investigate issues in production. - -[Datadog's Error Tracking](https://www.datadoghq.com/error-tracking/) groups similar errors together and provides detailed insights into their occurrences, stack traces, and affected services. OpenHands can automatically analyze these errors and provide detailed investigation reports. - -### Triggering Automated Debugging - -The GitHub Actions workflow can be triggered in two ways: - -1. **Search Query**: Provide a search query (e.g., "JSONDecodeError") to find all recent errors matching that pattern. This is useful for investigating categories of errors. - -2. **Specific Error ID**: Provide a specific Datadog error tracking ID to deep-dive into a known issue. You can copy the error ID from DataDog's error tracking UI using the "Actions" button. - -### Automated Investigation Process - -When the workflow runs, it automatically performs the following steps: - -1. Get detailed info from the DataDog API -2. Create or find an existing GitHub issue to track the error -3. Clone all relevant repositories to get full code context -4. Run an OpenHands agent to analyze the error and investigate the code -5. Post the findings as a comment on the GitHub issue - -The agent identifies the exact file and line number where errors originate, determines root causes, and provides specific recommendations for fixes. - - -The workflow posts findings to GitHub issues for human review before any code changes are made. If you want the agent to create a fix, you can follow up using the [OpenHands GitHub integration](https://docs.openhands.dev/openhands/usage/cloud/github-installation#github-integration) and say `@openhands go ahead and create a pull request to fix this issue based on your analysis`. - - -## Setting Up the Workflow - -To set up automated Datadog debugging in your own repository: - -1. Copy the workflow file to `.github/workflows/` in your repository -2. Configure the required secrets (Datadog API keys, LLM API key) -3. Customize the default queries and repository lists for your needs -4. Run the workflow manually or set up scheduled runs - -The workflow is fully customizable. You can modify the prompts to focus on specific types of analysis, adjust the agent's tools to fit your workflow, or extend it to integrate with other services beyond GitHub and Datadog. - -Find the [full implementation on GitHub](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging), including the workflow YAML file, Python script, and prompt template. - -## Manual Incident Investigation - -You can also use OpenHands directly to investigate incidents without the automated workflow. - -### Log Analysis - -OpenHands can analyze logs to identify patterns and anomalies: - -``` -Analyze these application logs for the incident that occurred at 14:32 UTC: - -1. Identify the first error or warning that appeared -2. Trace the sequence of events leading to the failure -3. Find any correlated errors across services -4. Identify the user or request that triggered the issue -5. Summarize the timeline of events -``` - -**Log analysis capabilities:** - -| Log Type | Analysis Capabilities | -|----------|----------------------| -| Application logs | Error patterns, exception traces, timing anomalies | -| Access logs | Traffic patterns, slow requests, error responses | -| System logs | Resource exhaustion, process crashes, system errors | -| Database logs | Slow queries, deadlocks, connection issues | - -### Stack Trace Analysis - -Deep dive into stack traces: - -``` -Analyze this stack trace from our production error: - -[paste full stack trace] - -1. Identify the exception type and message -2. Trace back to our code (not framework code) -3. Identify the likely cause -4. Check if this code path has changed recently -5. Suggest a fix -``` - -**Multi-language support:** - - - - ``` - Analyze this Java exception: - - java.lang.OutOfMemoryError: Java heap space - at java.util.Arrays.copyOf(Arrays.java:3210) - at java.util.ArrayList.grow(ArrayList.java:265) - at com.myapp.DataProcessor.loadAllRecords(DataProcessor.java:142) - - Identify: - 1. What operation is consuming memory? - 2. Is there a memory leak or just too much data? - 3. What's the fix? - ``` - - - ``` - Analyze this Python traceback: - - Traceback (most recent call last): - File "app/api/orders.py", line 45, in create_order - order = OrderService.create(data) - File "app/services/order.py", line 89, in create - inventory.reserve(item_id, quantity) - AttributeError: 'NoneType' object has no attribute 'reserve' - - What's None and why? - ``` - - - ``` - Analyze this Node.js error: - - TypeError: Cannot read property 'map' of undefined - at processItems (/app/src/handlers/items.js:23:15) - at async handleRequest (/app/src/api/router.js:45:12) - - What's undefined and how should we handle it? - ``` - - - -### Root Cause Analysis - -Identify the underlying cause of an incident: - -``` -Perform root cause analysis for this incident: - -Symptoms: -- API response times increased 5x at 14:00 -- Error rate jumped from 0.1% to 15% -- Database CPU spiked to 100% - -Available data: -- Application metrics (Grafana dashboard attached) -- Recent deployments: v2.3.1 deployed at 13:45 -- Database slow query log (attached) - -Identify the root cause using the 5 Whys technique. -``` - -## Common Incident Patterns - -OpenHands can recognize and help diagnose these common patterns: - -- **Connection pool exhaustion**: Increasing connection errors followed by complete failure -- **Memory leaks**: Gradual memory increase leading to OOM -- **Cascading failures**: One service failure triggering others -- **Thundering herd**: Simultaneous requests overwhelming a service -- **Split brain**: Inconsistent state across distributed components - -## Quick Fix Generation - -Once the root cause is identified, generate fixes: - -``` -We've identified the root cause: a missing null check in OrderProcessor.java line 156. - -Generate a fix that: -1. Adds proper null checking -2. Logs when null is encountered -3. Returns an appropriate error response -4. Includes a unit test for the edge case -5. Is minimally invasive for a hotfix -``` - -## Best Practices - -### Investigation Checklist - -Use this checklist when investigating: - -1. **Scope the impact** - - How many users affected? - - What functionality is broken? - - What's the business impact? - -2. **Establish timeline** - - When did it start? - - What changed around that time? - - Is it getting worse or stable? - -3. **Gather data** - - Application logs - - Infrastructure metrics - - Recent deployments - - Configuration changes - -4. **Form hypotheses** - - List possible causes - - Rank by likelihood - - Test systematically - -5. **Implement fix** - - Choose safest fix - - Test before deploying - - Monitor after deployment - -### Common Pitfalls - - -Avoid these common incident response mistakes: - -- **Jumping to conclusions**: Gather data before assuming the cause -- **Changing multiple things**: Make one change at a time to isolate effects -- **Not documenting**: Record all actions for the post-mortem -- **Ignoring rollback**: Always have a rollback plan before deploying fixes - - - -For production incidents, always follow your organization's incident response procedures. OpenHands is a tool to assist your investigation, not a replacement for proper incident management. - - -## Related Resources - -- [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents -- [Datadog Debugging Workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) - Ready-to-use GitHub Actions workflow -- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts diff --git a/openhands/usage/use-cases/spark-migrations.mdx b/openhands/usage/use-cases/spark-migrations.mdx deleted file mode 100644 index b4c213be..00000000 --- a/openhands/usage/use-cases/spark-migrations.mdx +++ /dev/null @@ -1,391 +0,0 @@ ---- -title: TODO-Spark Migrations -description: Migrating Apache Spark applications with OpenHands ---- - -Apache Spark is constantly evolving, and keeping your data pipelines up to date is essential for performance, security, and access to new features. OpenHands can help you migrate Spark applications across versions, frameworks, and cloud platforms. - -## Overview - -OpenHands assists with Spark migrations in several ways: - -- **Version upgrades**: Migrate from Spark 2.x to 3.x, or between 3.x versions -- **API modernization**: Update deprecated APIs to current best practices -- **Framework migrations**: Convert from MapReduce, Hive, or other frameworks to Spark -- **Cloud migrations**: Move Spark workloads between cloud providers or to cloud-native services - -## Migration Scenarios - -### Spark Version Upgrades - -Upgrading Spark versions often requires code changes due to API deprecations and behavioral differences. - -**Spark 2.x to 3.x Migration:** - -``` -Migrate my Spark 2.4 application to Spark 3.5: - -1. Identify all deprecated API usages in src/main/scala/ -2. Update DataFrame operations that changed behavior -3. Migrate from SparkSession.builder() patterns if needed -4. Update date/time handling for the new defaults -5. Check and update all UDF registrations -6. Update the build.sbt dependencies - -List all changes made with before/after comparisons. -``` - -**Common migration areas:** - -| Spark 2.x | Spark 3.x | Action Required | -|-----------|-----------|-----------------| -| `SQLContext` | `SparkSession` | Replace with SparkSession | -| `HiveContext` | `SparkSession` with Hive | Update initialization | -| `Dataset.unionAll()` | `Dataset.union()` | Rename method calls | -| `DataFrame.explode()` | `functions.explode()` | Use SQL functions | -| Legacy date parsing | Proleptic Gregorian calendar | Review date handling | - -### Migration from Other Big Data Frameworks - -**MapReduce to Spark:** - -``` -Convert our MapReduce jobs to Spark: - -1. Analyze the MapReduce job in src/mapreduce/WordCount.java -2. Identify the mapper and reducer logic -3. Convert to equivalent Spark transformations -4. Preserve the same input/output formats -5. Create a test that compares outputs from both versions -``` - -**Hive to Spark SQL:** - -``` -Migrate our Hive ETL pipeline to Spark: - -1. Convert the Hive scripts in etl/hive/ to Spark SQL -2. Replace Hive UDFs with Spark SQL functions where possible -3. For custom UDFs, create Spark UDF equivalents -4. Maintain compatibility with our existing Hive metastore -5. Benchmark the performance difference -``` - -**Pig to Spark:** - -``` -Convert our Pig Latin scripts to PySpark: - -1. Analyze the Pig scripts in pipelines/pig/ -2. Map Pig operations to equivalent Spark transformations -3. Convert Pig UDFs to Python functions -4. Preserve the data flow and dependencies -5. Document any behavioral differences -``` - -### Cloud Platform Migrations - -**On-premises to Cloud:** - - - - ``` - Migrate our Spark application to AWS EMR: - - 1. Update file paths from HDFS to S3 - 2. Configure AWS credentials handling - 3. Update cluster configuration for EMR - 4. Modify logging to use CloudWatch - 5. Create EMR step definitions for our jobs - 6. Update the CI/CD pipeline for EMR deployment - ``` - - - ``` - Migrate our Spark jobs to Databricks: - - 1. Convert batch jobs to Databricks notebooks - 2. Update file I/O to use DBFS or Unity Catalog - 3. Configure cluster policies and instance pools - 4. Set up Databricks Jobs for scheduling - 5. Migrate secrets to Databricks secret scopes - 6. Update monitoring to use Databricks metrics - ``` - - - ``` - Migrate our Spark workloads to Dataproc: - - 1. Update storage paths to use GCS - 2. Configure service account authentication - 3. Create Dataproc workflow templates - 4. Set up Cloud Logging and Monitoring - 5. Update dependencies for GCP libraries - 6. Configure autoscaling policies - ``` - - - -**Between Cloud Providers:** - -``` -Migrate our Spark application from EMR to Databricks: - -1. Inventory all EMR-specific configurations -2. Map S3 paths to DBFS equivalents -3. Convert EMR bootstrap scripts to init scripts -4. Update IAM roles to Databricks service principals -5. Migrate Step Functions orchestration to Databricks Workflows -6. Create a parallel testing strategy -``` - -## Code Transformation - -### API Updates - -OpenHands can automatically update deprecated APIs: - -``` -Update all deprecated Spark APIs in our codebase: - -1. Scan for deprecated method usages -2. Replace with recommended alternatives -3. Update import statements as needed -4. Add comments noting the changes for review -5. Run the test suite to verify no regressions -``` - -**Common API updates:** - -```scala -// Before (Spark 2.x) -val df = spark.read.format("json").load(path) -df.registerTempTable("temp") - -// After (Spark 3.x) -val df = spark.read.format("json").load(path) -df.createOrReplaceTempView("temp") -``` - -### Performance Optimization - -Improve performance during migration: - -``` -Optimize our Spark jobs during the migration: - -1. Replace `collect()` with `take()` or `foreach()` where appropriate -2. Convert repeated DataFrame operations to use caching -3. Optimize shuffle operations with appropriate partitioning -4. Replace narrow transformations grouped after wide ones -5. Update broadcast join hints for large dimension tables -6. Profile before and after with Spark UI metrics -``` - -**Key optimization patterns:** - -| Anti-pattern | Optimization | Impact | -|--------------|--------------|--------| -| Multiple `count()` calls | Cache and count once | Reduces recomputation | -| Small file output | Coalesce before write | Fewer files, faster reads | -| Skewed joins | Salting or broadcast | Eliminates stragglers | -| UDFs for simple ops | Built-in functions | Catalyst optimization | - -### Best Practices Application - -Apply modern Spark best practices: - -``` -Refactor our Spark application to follow best practices: - -1. Replace RDD operations with DataFrame/Dataset where possible -2. Use Spark SQL functions instead of UDFs -3. Implement proper error handling with try-catch -4. Add schema validation for input data -5. Implement idempotent writes for recovery -6. Add structured logging for debugging -``` - -## Testing and Validation - -### Job Testing - -Create comprehensive tests for migrated jobs: - -``` -Create a test suite for our migrated Spark jobs: - -1. Unit tests for transformation logic using local SparkSession -2. Integration tests with sample data files -3. Schema validation tests for input and output -4. Property-based tests for key business logic -5. Test fixtures that work with both Spark versions -``` - -**Example test structure:** - -```scala -class MigrationTest extends AnyFunSuite with SparkSessionTestWrapper { - test("transformed output matches expected schema") { - val input = spark.read.json("src/test/resources/input.json") - val result = MyTransformations.process(input) - - assert(result.schema === expectedSchema) - } - - test("business logic produces same results as legacy") { - val input = loadTestData() - val newResult = NewPipeline.run(input) - val legacyResult = loadLegacyOutput() - - assertDataFrameEquals(newResult, legacyResult) - } -} -``` - -### Performance Benchmarking - -Compare performance between versions: - -``` -Create performance benchmarks for our migration: - -1. Set up identical test datasets of 1GB, 10GB, and 100GB -2. Measure job completion time for both versions -3. Compare resource utilization (CPU, memory, shuffle) -4. Track stage-level metrics from Spark UI -5. Generate a comparison report with recommendations -``` - -**Benchmark metrics to track:** - -- Job duration (wall clock time) -- Shuffle read/write bytes -- Peak executor memory -- Task distribution (min/max/median) -- Garbage collection time - -### Data Validation - -Ensure data correctness after migration: - -``` -Validate that our migrated pipeline produces correct output: - -1. Run both pipelines on the same input dataset -2. Compare row counts between outputs -3. Perform checksum comparison on key columns -4. Validate aggregations match exactly -5. Check for NULL handling differences -6. Generate a data quality report -``` - -**Validation approaches:** - - - - ```python - # Compare outputs row by row - old_df = spark.read.parquet("output/v2/") - new_df = spark.read.parquet("output/v3/") - - diff = old_df.exceptAll(new_df) - assert diff.count() == 0, f"Found {diff.count()} differences" - ``` - - - ```python - # Compare key metrics - old_stats = old_df.agg( - count("*"), sum("amount"), avg("quantity") - ).collect()[0] - - new_stats = new_df.agg( - count("*"), sum("amount"), avg("quantity") - ).collect()[0] - - assert old_stats == new_stats - ``` - - - ```python - # Compare schemas - assert old_df.schema == new_df.schema, \ - f"Schema mismatch: {old_df.schema} vs {new_df.schema}" - ``` - - - -## Examples - -### Complete Spark 2 to 3 Migration - -``` -Migrate our Spark 2.4 ETL pipeline to Spark 3.5: - -Project structure: -- src/main/scala/etl/ - - ExtractJob.scala - - TransformJob.scala - - LoadJob.scala -- src/main/resources/ - - application.conf - -Requirements: -1. Update all deprecated APIs -2. Migrate from legacy date parsing -3. Update to new Catalog API for Hive tables -4. Preserve all business logic exactly -5. Update build.sbt with new dependencies -6. Create a test suite comparing old and new outputs -7. Document all breaking changes found -``` - -### Hive to Spark SQL Migration - -``` -Convert our Hive data warehouse queries to Spark SQL: - -Hive scripts to migrate: -- daily_aggregation.hql -- customer_segments.hql -- revenue_report.hql - -Requirements: -1. Convert HiveQL to Spark SQL -2. Replace Hive UDFs with Spark equivalents -3. Optimize for Spark execution -4. Maintain Hive metastore compatibility -5. Create performance comparison benchmarks -``` - -### EMR to Databricks Migration - -``` -Migrate our EMR Spark pipeline to Databricks: - -Current setup: -- EMR 6.x with Spark 3.1 -- S3 for data storage -- Step Functions for orchestration -- CloudWatch for monitoring - -Target: -- Databricks on AWS -- Unity Catalog for data governance -- Databricks Workflows for orchestration -- Built-in Databricks monitoring - -Deliverables: -1. Converted notebook or job definitions -2. Updated storage configurations -3. Workflow definitions -4. IAM/service principal mappings -5. Migration runbook -``` - -## Related Resources - -- [Repository Setup](/openhands/usage/customization/repository) - Configure your Spark repository for OpenHands -- [Key Features](/openhands/usage/key-features) - OpenHands capabilities overview -- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx deleted file mode 100644 index 39813dfd..00000000 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: Vulnerability Remediation -description: Using OpenHands to identify and fix security vulnerabilities in your codebase ---- - -Security vulnerabilities are a constant challenge for software teams. Every day, new security issues are discovered—from vulnerabilities in dependencies to code security flaws detected by static analysis tools. The National Vulnerability Database (NVD) reports thousands of new vulnerabilities annually, and organizations struggle to keep up with this constant influx. - -## The Challenge - -The traditional approach to vulnerability remediation is manual and time-consuming: - -1. Scan repositories for vulnerabilities -2. Review each vulnerability and its impact -3. Research the fix (usually a version upgrade) -4. Update dependency files -5. Test the changes -6. Create pull requests -7. Get reviews and merge - -This process can take hours per vulnerability, and with hundreds or thousands of vulnerabilities across multiple repositories, it becomes an overwhelming task. Security debt accumulates faster than teams can address it. - -**What if we could automate this entire process using AI agents?** - -## Automated Vulnerability Remediation with OpenHands - -The [OpenHands Software Agents SDK](https://docs.openhands.dev/sdk) provides powerful capabilities for building autonomous AI agents capable of interacting with codebases. These agents can tackle one of the most tedious tasks in software maintenance: **security vulnerability remediation**. - -OpenHands assists with vulnerability remediation by: - -- **Identifying vulnerabilities**: Analyzing code for common security issues -- **Understanding impact**: Explaining the risk and exploitation potential -- **Implementing fixes**: Generating secure code to address vulnerabilities -- **Validating remediation**: Verifying fixes are effective and complete - -## Two Approaches to Vulnerability Fixing - -### 1. Point to a GitHub Repository - -Build a workflow where users can point to a GitHub repository, scan it for vulnerabilities, and have OpenHands AI agents automatically create pull requests with fixes—all with minimal human intervention. - -### 2. Upload Security Scanner Reports - -Enable users to upload reports from security scanners such as Snyk (as well as other third-party security scanners) where OpenHands agents automatically detect the report format, identify the issues, and apply fixes. - -This solution goes beyond automation—it focuses on making security remediation accessible, fast, and scalable. - -## Architecture Overview - -A vulnerability remediation agent can be built as a web application that orchestrates agents using the [OpenHands Software Agents SDK](https://docs.openhands.dev/sdk) and [OpenHands Cloud](https://docs.openhands.dev/openhands/usage/key-features) to perform security scans and automate remediation fixes. - -The key architectural components include: - -- **Frontend**: Communicates directly with the OpenHands Agent Server through the [TypeScript Client](https://github.com/OpenHands/typescript-client) -- **WebSocket interface**: Enables real-time status updates on agent actions and operations -- **LLM flexibility**: OpenHands supports multiple LLMs, minimizing dependency on any single provider -- **Scalable execution**: The Agent Server can be hosted locally, with self-hosted models, or integrated with OpenHands Cloud - -This architecture allows the frontend to remain lightweight while heavy lifting happens in the agent's execution environment. - -## Example: Vulnerability Fixer Application - -An example implementation is available at [github.com/OpenHands/vulnerability-fixer](https://github.com/OpenHands/vulnerability-fixer). This React web application demonstrates the full workflow: - -1. User points to a repository or uploads a security scan report -2. Agent analyzes the vulnerabilities -3. Agent creates fixes and pull requests automatically -4. User reviews and merges the changes - -## Security Scanning Integration - -Use OpenHands to analyze security scanner output: - -``` -We ran a security scan and found these issues. Analyze each one: - -1. SQL Injection in src/api/users.py:45 -2. XSS in src/templates/profile.html:23 -3. Hardcoded credential in src/config/database.py:12 -4. Path traversal in src/handlers/files.py:67 - -For each vulnerability: -- Explain what the vulnerability is -- Show how it could be exploited -- Rate the severity (Critical/High/Medium/Low) -- Suggest a fix -``` - -## Common Vulnerability Patterns - -OpenHands can detect these common vulnerability patterns: - -| Vulnerability | Pattern | Example | -|--------------|---------|---------| -| SQL Injection | String concatenation in queries | `query = "SELECT * FROM users WHERE id=" + user_id` | -| XSS | Unescaped user input in HTML | `
${user_comment}
` | -| Path Traversal | Unvalidated file paths | `open(user_supplied_path)` | -| Command Injection | Shell commands with user input | `os.system("ping " + hostname)` | -| Hardcoded Secrets | Credentials in source code | `password = "admin123"` | - -## Automated Remediation - -### Applying Security Patches - -Fix identified vulnerabilities: - - - - ``` - Fix the SQL injection vulnerability in src/api/users.py: - - Current code: - query = f"SELECT * FROM users WHERE id = {user_id}" - cursor.execute(query) - - Requirements: - 1. Use parameterized queries - 2. Add input validation - 3. Maintain the same functionality - 4. Add a test case for the fix - ``` - - **Fixed code:** - ```python - # Using parameterized query - query = "SELECT * FROM users WHERE id = %s" - cursor.execute(query, (user_id,)) - ``` - - - ``` - Fix the XSS vulnerability in src/templates/profile.html: - - Current code: -
${user.bio}
- - Requirements: - 1. Properly escape user content - 2. Consider Content Security Policy - 3. Handle rich text if needed - 4. Test with malicious input - ``` - - **Fixed code:** - ```html - -
{{ user.bio | escape }}
- ``` - - - ``` - Fix the command injection in src/utils/network.py: - - Current code: - def ping_host(hostname): - os.system(f"ping -c 1 {hostname}") - - Requirements: - 1. Use safe subprocess calls - 2. Validate input format - 3. Avoid shell=True - 4. Handle errors properly - ``` - - **Fixed code:** - ```python - import subprocess - import re - - def ping_host(hostname): - # Validate hostname format - if not re.match(r'^[a-zA-Z0-9.-]+$', hostname): - raise ValueError("Invalid hostname") - - # Use subprocess without shell - result = subprocess.run( - ["ping", "-c", "1", hostname], - capture_output=True, - text=True - ) - return result.returncode == 0 - ``` - - - -### Code-Level Vulnerability Fixes - -Fix application-level security issues: - -``` -Fix the broken access control in our API: - -Issue: Users can access other users' data by changing the ID in the URL. - -Current code: -@app.get("/api/users/{user_id}/documents") -def get_documents(user_id: int): - return db.get_documents(user_id) - -Requirements: -1. Add authorization check -2. Verify requesting user matches or is admin -3. Return 403 for unauthorized access -4. Log access attempts -5. Add tests for authorization -``` - -**Fixed code:** - -```python -@app.get("/api/users/{user_id}/documents") -def get_documents(user_id: int, current_user: User = Depends(get_current_user)): - # Check authorization - if current_user.id != user_id and not current_user.is_admin: - logger.warning(f"Unauthorized access attempt: user {current_user.id} tried to access user {user_id}'s documents") - raise HTTPException(status_code=403, detail="Not authorized") - - return db.get_documents(user_id) -``` - -## Security Testing - -Test your fixes thoroughly: - -``` -Create security tests for the SQL injection fix: - -1. Test with normal input -2. Test with SQL injection payloads: - - ' OR '1'='1 - - '; DROP TABLE users; -- - - UNION SELECT * FROM passwords -3. Test with special characters -4. Test with null/empty input -5. Verify error handling doesn't leak information -``` - -## Automated Remediation Pipeline - -Create an end-to-end automated pipeline: - -``` -Create an automated vulnerability remediation pipeline: - -1. Parse Snyk/Dependabot/CodeQL alerts -2. Categorize by severity and type -3. For each vulnerability: - - Create a branch - - Apply the fix - - Run tests - - Create a PR with: - - Description of vulnerability - - Fix applied - - Test results -4. Request review from security team -5. Auto-merge low-risk fixes after tests pass -``` - -## Building Your Own Vulnerability Fixer - -The example application demonstrates that AI agents can effectively automate security maintenance at scale. Tasks that required hours of manual effort per vulnerability can now be completed in minutes with minimal human intervention. - -To build your own vulnerability remediation agent: - -1. Use the [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk) to create your agent -2. Integrate with your security scanning tools (Snyk, Dependabot, CodeQL, etc.) -3. Configure the agent to create pull requests automatically -4. Set up human review workflows for critical fixes - -As agent capabilities continue to evolve, an increasing number of repetitive and time-consuming security tasks can be automated, enabling developers to focus on higher-level design, innovation, and problem-solving rather than routine maintenance. - -## Related Resources - -- [Vulnerability Fixer Example](https://github.com/OpenHands/vulnerability-fixer) - Full implementation example -- [OpenHands SDK Documentation](https://docs.openhands.dev/sdk) - Build custom AI agents -- [Dependency Upgrades](/openhands/usage/use-cases/dependency-upgrades) - Updating vulnerable dependencies -- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts diff --git a/overview/quickstart.mdx b/overview/quickstart.mdx index 40c06cf8..54bfb9fd 100644 --- a/overview/quickstart.mdx +++ b/overview/quickstart.mdx @@ -1,32 +1,19 @@ --- title: Quick Start -description: Choose how you want to run OpenHands +description: Running OpenHands Cloud or running on your own. --- -Get started with OpenHands in minutes. Choose the option that works best for you. + + + The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $10 in free credits for new users. - - - **Recommended** + To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev). - The fastest way to get started. No setup required—just sign in and start coding. + For more information see [getting started with OpenHands Cloud.](/openhands/usage/cloud/openhands-cloud) + + + Run OpenHands on your local system and bring your own LLM and API key. - - $10 in free credits for new users - - No installation needed - - Managed infrastructure - - - Run OpenHands locally with a web-based interface. Bring your own LLM and API key. - - - Full control over your environment - - Works offline - - Docker-based setup - - - Use OpenHands from your terminal. Perfect for automation and scripting. - - - IDE integrations available - - Headless mode for CI/CD - - Lightweight installation - - + For more information see [running OpenHands on your own.](/openhands/usage/run-openhands/local-setup) + +