From 117c9508fd46acbd40212c59b5dac43371706652 Mon Sep 17 00:00:00 2001 From: jpelletier1 <44589723+jpelletier1@users.noreply.github.com> Date: Thu, 29 Jan 2026 20:19:54 -0500 Subject: [PATCH 01/19] Initial layout This is an initial layout that roughly mimics Devin docs. It attempts to separate Documentation and Use Cases. --- docs.json | 327 +++++++++--------- openhands/usage/admin/billing.mdx | 78 +++++ openhands/usage/admin/security.mdx | 76 ++++ .../good-vs-bad-instructions.mdx | 62 ++++ .../essential-guidelines/sdlc-integration.mdx | 56 +++ .../when-to-use-openhands.mdx | 46 +++ openhands/usage/get-started/tutorials.mdx | 30 ++ .../usage/product-guides/session-insights.mdx | 44 +++ .../usage/use-cases/cobol-modernization.mdx | 36 ++ openhands/usage/use-cases/code-review.mdx | 37 ++ .../usage/use-cases/dependency-upgrades.mdx | 36 ++ openhands/usage/use-cases/incident-triage.mdx | 36 ++ .../usage/use-cases/spark-migrations.mdx | 36 ++ .../use-cases/vulnerability-remediation.mdx | 36 ++ 14 files changed, 780 insertions(+), 156 deletions(-) create mode 100644 openhands/usage/admin/billing.mdx create mode 100644 openhands/usage/admin/security.mdx create mode 100644 openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx create mode 100644 openhands/usage/essential-guidelines/sdlc-integration.mdx create mode 100644 openhands/usage/essential-guidelines/when-to-use-openhands.mdx create mode 100644 openhands/usage/get-started/tutorials.mdx create mode 100644 openhands/usage/product-guides/session-insights.mdx create mode 100644 openhands/usage/use-cases/cobol-modernization.mdx create mode 100644 openhands/usage/use-cases/code-review.mdx create mode 100644 openhands/usage/use-cases/dependency-upgrades.mdx create mode 100644 openhands/usage/use-cases/incident-triage.mdx create mode 100644 openhands/usage/use-cases/spark-migrations.mdx create mode 100644 openhands/usage/use-cases/vulnerability-remediation.mdx diff --git a/docs.json b/docs.json index 977858db..a0b77e13 100644 --- a/docs.json +++ b/docs.json @@ -20,22 +20,36 @@ "navigation": { "tabs": [ { - "tab": "Overview", + "tab": "Documentation", "pages": [ { - "group": "Overview", + "group": "Get Started", "pages": [ "overview/introduction", "overview/quickstart", - "overview/first-projects", - "overview/faqs", - "overview/community", - "overview/contributing" + "openhands/usage/get-started/tutorials" ] }, { - "group": "Common Features", + "group": "Essential Guidelines", "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", @@ -46,95 +60,167 @@ "overview/skills/org", "overview/skills/public" ] + }, + "openhands/usage/settings/secrets-settings", + "openhands/usage/product-guides/session-insights", + { + "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", + "openhands/usage/admin/security", + "openhands/usage/admin/billing" + ] } ] }, { - "group": "Tips and Tricks", - "pages": [ - "openhands/usage/tips/prompting-best-practices" - ] - }, - { - "group": "Help", - "pages": [ - "openhands/usage/troubleshooting/troubleshooting", - "openhands/usage/troubleshooting/feedback" - ] - } - ] - }, - { - "tab": "Web", - "pages": [ - { - "group": "Key Features", + "group": "Integrations", "pages": [ - "openhands/usage/key-features" + "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" + ] + } ] }, { - "group": "OpenHands Cloud", + "group": "CLI", "pages": [ - "openhands/usage/cloud/openhands-cloud", { - "group": "Integrations", + "group": "Getting Started", + "pages": [ + "openhands/usage/cli/installation", + "openhands/usage/cli/quick-start" + ] + }, + { + "group": "Ways to Run", "pages": [ - "openhands/usage/cloud/bitbucket-installation", - "openhands/usage/cloud/github-installation", - "openhands/usage/cloud/gitlab-installation", - "openhands/usage/cloud/slack-installation", + "openhands/usage/cli/terminal", + "openhands/usage/cli/headless", + "openhands/usage/cli/web-interface", + "openhands/usage/cli/gui-server", { - "group": "Project Management Tools", + "group": "IDE Integration (ACP)", "pages": [ - "openhands/usage/cloud/project-management/jira-integration" + "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" ] } ] }, - "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": "OpenHands Settings", + "group": "Cloud", "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" + "openhands/usage/cli/cloud" + ] + }, + { + "group": "Extensions", + "pages": [ + "openhands/usage/cli/mcp-servers", + "openhands/usage/cli/critic" ] }, - "openhands/usage/customization/repository" + { + "group": "Reference", + "pages": [ + "openhands/usage/cli/command-reference", + "openhands/usage/cli/resume" + ] + } ] }, { - "group": "Advanced Configuration", + "group": "Additional Documentation", "pages": [ + { + "group": "V0 Reference", + "pages": [ + "openhands/usage/v0/runtimes/V0_overview", + { + "group": "V0 Runtime Providers", + "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/v0/advanced/V0_configuration-options", + { + "group": "V0 REST API", + "openapi": "openapi/V0_openapi.json" + } + ] + }, + { + "group": "Local GUI", + "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" + ] + } + ] + }, { "group": "LLM Configuration", "pages": [ "openhands/usage/llms/llms", { - "group": "Providers", + "group": "LLM Providers", "pages": [ "openhands/usage/llms/openhands-llms", "openhands/usage/llms/azure-llms", @@ -150,113 +236,42 @@ ] }, { - "group": "Sandbox Configuration", + "group": "Developers", "pages": [ - "openhands/usage/sandboxes/overview", - { - "group": "Providers", - "pages": [ - "openhands/usage/sandboxes/docker", - "openhands/usage/sandboxes/remote", - "openhands/usage/sandboxes/process" - ] - } + "openhands/usage/developers/development-overview", + "openhands/usage/developers/debugging", + "openhands/usage/developers/websocket-connection", + "openhands/usage/developers/evaluation-harness" ] }, - "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": "Providers", + "group": "Community", "pages": [ - "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" - ] - } + "overview/community", + "overview/contributing", + "overview/faqs", + "openhands/usage/troubleshooting/feedback" ] } ] - }, - { - "group": "V0 Configuration Options", - "pages": [ - "openhands/usage/v0/advanced/V0_configuration-options" - ] - }, - { - "group": "V0 REST API", - "openapi": "openapi/V0_openapi.json" } ] }, { - "tab": "CLI", + "tab": "Use Cases", "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", + "group": "Use Cases", "pages": [ - "openhands/usage/cli/command-reference", - "openhands/usage/cli/resume" + "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" ] } + ] }, { diff --git a/openhands/usage/admin/billing.mdx b/openhands/usage/admin/billing.mdx new file mode 100644 index 00000000..6835f2db --- /dev/null +++ b/openhands/usage/admin/billing.mdx @@ -0,0 +1,78 @@ +--- +title: TODO-Billing +description: Usage tracking and billing for OpenHands Cloud +--- + +# TODO-Billing + +## Usage Tracking for OpenHands Cloud + +### Understanding Usage Metrics + +### Billable Activities + +### Usage Dashboard + +### Usage Reports + +## Credit Management + +### Credit System Overview + +### Purchasing Credits + +### Credit Balance + +### Credit Expiration + +### Auto-Renewal + +## Billing Plans + +### Free Tier + +### Individual Plans + +### Team Plans + +### Enterprise Plans + +## Payment Methods + +### Supported Payment Options + +### Adding Payment Methods + +### Updating Payment Information + +### Payment Security + +## Invoicing + +### Invoice Generation + +### Downloading Invoices + +### Invoice History + +### Tax Information + +## Cost Optimization + +### Monitoring Usage + +### Setting Budgets + +### Usage Alerts + +### Cost-Saving Tips + +## Billing Support + +### Common Billing Questions + +### Refund Policy + +### Billing Disputes + +### Contact Billing Support diff --git a/openhands/usage/admin/security.mdx b/openhands/usage/admin/security.mdx new file mode 100644 index 00000000..446b66bd --- /dev/null +++ b/openhands/usage/admin/security.mdx @@ -0,0 +1,76 @@ +--- +title: TODO-Security +description: Comprehensive security overview for OpenHands +--- + +# TODO-Security + +## Comprehensive Security Overview + +### Security Architecture + +### Data Protection + +### Infrastructure Security + +### Network Security + +## Privacy & Intellectual Property + +### Data Privacy + +### Code Privacy + +### Intellectual Property Protection + +### Data Retention Policies + +## User Best Practices + +### Secure Configuration + +### Authentication Best Practices + +### Secret Management + +### Access Control + +## Third-Party Audits + +### Security Certifications + +### Compliance Standards + +### Audit Reports + +### Penetration Testing + +## Security Features + +### Encryption + +#### Data in Transit + +#### Data at Rest + +### Access Controls + +### Audit Logging + +### Vulnerability Management + +## Incident Response + +### Reporting Security Issues + +### Incident Response Process + +### Security Updates + +## Compliance + +### GDPR Compliance + +### SOC 2 Compliance + +### Other Certifications diff --git a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx new file mode 100644 index 00000000..dd875b8e --- /dev/null +++ b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx @@ -0,0 +1,62 @@ +--- +title: TODO-Good vs. Bad Instructions +description: Learn how to write effective instructions for OpenHands +--- + +# TODO-Good vs. Bad Instructions + +## Concrete Examples of Good/Bad Prompts + +### Bug Fixing Examples + +#### Bad Example + +#### Good Example + +### Feature Development Examples + +#### Bad Example + +#### Good Example + +### Code Review Examples + +#### Bad Example + +#### Good Example + +### Refactoring Examples + +#### Bad Example + +#### Good Example + +## Key Principles for Effective Instructions + +### Be Specific + +### Provide Context + +### Set Clear Goals + +### Include Constraints + +## Common Pitfalls to Avoid + +### Vague Requirements + +### Missing Context + +### Unrealistic Expectations + +### Incomplete Information + +## Best Practices + +### Structure Your Instructions + +### Provide Examples + +### Define Success Criteria + +### Iterate and Refine diff --git a/openhands/usage/essential-guidelines/sdlc-integration.mdx b/openhands/usage/essential-guidelines/sdlc-integration.mdx new file mode 100644 index 00000000..fe81b71f --- /dev/null +++ b/openhands/usage/essential-guidelines/sdlc-integration.mdx @@ -0,0 +1,56 @@ +--- +title: TODO-OpenHands in Your SDLC +description: How OpenHands fits into your software development lifecycle +--- + +# TODO-OpenHands in Your SDLC + +## Integration with Development Workflows + +### Planning Phase + +### Development Phase + +### Testing Phase + +### Review Phase + +### Deployment Phase + +## CI/CD Integration + +### GitHub Actions Integration + +### GitLab CI Integration + +### Jenkins Integration + +### Other CI/CD Platforms + +## Team Workflows + +### Solo Developer Workflows + +### Small Team Workflows + +### Enterprise Team Workflows + +## Best Practices + +### Code Review Integration + +### Pull Request Automation + +### Quality Gates + +### Automated Testing + +## Common Integration Patterns + +### Pre-Commit Hooks + +### Post-Commit Actions + +### Scheduled Tasks + +### Event-Triggered Workflows diff --git a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx new file mode 100644 index 00000000..05bdf478 --- /dev/null +++ b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx @@ -0,0 +1,46 @@ +--- +title: TODO-When to Use OpenHands +description: Guidance on when OpenHands is the right tool for your task +--- + +# TODO-When to Use OpenHands + +## Task Complexity Guidance + +### Simple Tasks + +### Medium Complexity Tasks + +### Complex Tasks + +## Best Use Cases + +### Ideal Scenarios + +### Good Fit Scenarios + +### Poor Fit Scenarios + +## Limitations + +### Current Limitations + +### Technical Constraints + +### Scope Boundaries + +## Pre-Task Checklist + +### Prerequisites + +### Environment Setup + +### Repository Preparation + +## Post-Task Review + +### Quality Checks + +### Validation Steps + +### Learning from Results diff --git a/openhands/usage/get-started/tutorials.mdx b/openhands/usage/get-started/tutorials.mdx new file mode 100644 index 00000000..fa355e66 --- /dev/null +++ b/openhands/usage/get-started/tutorials.mdx @@ -0,0 +1,30 @@ +--- +title: TODO-Tutorial Library +description: Centralized hub for OpenHands tutorials and examples +--- + +# TODO-Tutorial Library + +## Categories: Testing, Data Analysis, Web Scraping, etc. + +### Task Complexity Guidance + +### Best Use Cases + +### Example Tutorials by Category + +#### Testing + +#### Data Analysis + +#### Web Scraping + +#### Code Review + +#### Bug Fixing + +#### Feature Development + +### Getting Started with Tutorials + +### Contributing Tutorials diff --git a/openhands/usage/product-guides/session-insights.mdx b/openhands/usage/product-guides/session-insights.mdx new file mode 100644 index 00000000..7bd28032 --- /dev/null +++ b/openhands/usage/product-guides/session-insights.mdx @@ -0,0 +1,44 @@ +--- +title: TODO-Session Insights +description: Analyze and improve your OpenHands sessions +--- + +# TODO-Session Insights + +## How to Analyze Session Performance + +### Understanding Session Metrics + +### Key Performance Indicators + +### Success Criteria + +### Common Patterns + +## Feedback Loops and Improvement Suggestions + +### Collecting Feedback + +### Analyzing Session Results + +### Identifying Areas for Improvement + +### Implementing Improvements + +## Session Analytics Dashboard + +### Overview Metrics + +### Detailed Analytics + +### Historical Trends + +## Best Practices for Session Management + +### Planning Sessions + +### Monitoring Progress + +### Post-Session Review + +### Continuous Improvement diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx new file mode 100644 index 00000000..35103cc7 --- /dev/null +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -0,0 +1,36 @@ +--- +title: TODO-COBOL Modernization +description: Modernizing legacy COBOL systems with OpenHands +--- + +# TODO-COBOL Modernization + +## Overview + +Content coming soon. This page will cover how to use OpenHands to modernize legacy COBOL codebases. + +## Key Topics + +### Code Analysis +- COBOL code understanding +- Business logic extraction +- Dependency mapping + +### Modernization Strategies +- Translation to modern languages +- Refactoring approaches +- Incremental migration + +### Testing and Validation +- Behavior preservation +- Regression testing +- Output validation + +## Examples + +Examples and tutorials coming soon. + +## Related Resources + +- [Repository Setup](/openhands/usage/customization/repository) +- [Key Features](/openhands/usage/key-features) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx new file mode 100644 index 00000000..1dfc87bf --- /dev/null +++ b/openhands/usage/use-cases/code-review.mdx @@ -0,0 +1,37 @@ +--- +title: TODO-Code Review +description: Leveraging OpenHands for automated and assisted code review +--- + +# TODO-Code Review + +## Overview + +Content coming soon. This page will cover how to use OpenHands to enhance your code review process. + +## Key Topics + +### Automated Code Review +- Code quality analysis +- Style and standards enforcement +- Bug detection + +### Review Assistance +- Generating review comments +- Identifying potential issues +- Suggesting improvements + +### Integration +- GitHub pull request integration +- GitLab merge request integration +- CI/CD pipeline integration + +## Examples + +Examples and tutorials coming soon. + +## Related Resources + +- [GitHub Integration](/openhands/usage/cloud/github-installation) +- [GitLab Integration](/openhands/usage/cloud/gitlab-installation) +- [Integrations Overview](/openhands/usage/settings/integrations-settings) diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx new file mode 100644 index 00000000..a7a5ec62 --- /dev/null +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -0,0 +1,36 @@ +--- +title: TODO-Dependency Upgrades +description: Automating dependency updates and upgrades with OpenHands +--- + +# TODO-Dependency Upgrades + +## Overview + +Content coming soon. This page will cover how to use OpenHands to automate dependency upgrades and manage breaking changes. + +## Key Topics + +### Dependency Analysis +- Identifying outdated dependencies +- Security vulnerability scanning +- Compatibility checking + +### Automated Upgrades +- Version updates +- Breaking change handling +- Code adaptation + +### Testing and Validation +- Automated test execution +- Integration testing +- Regression detection + +## Examples + +Examples and tutorials coming soon. + +## Related Resources + +- [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) +- [Security Admin](/openhands/usage/admin/security) diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx new file mode 100644 index 00000000..6559774b --- /dev/null +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -0,0 +1,36 @@ +--- +title: TODO-Incident Triage +description: Using OpenHands to investigate and resolve production incidents +--- + +# TODO-Incident Triage + +## Overview + +Content coming soon. This page will cover how to use OpenHands for rapid incident investigation and resolution. + +## Key Topics + +### Incident Investigation +- Log analysis +- Error tracking +- Root cause analysis + +### Automated Diagnosis +- Pattern recognition +- Stack trace analysis +- System state investigation + +### Rapid Response +- Quick fix generation +- Hotfix deployment +- Documentation generation + +## Examples + +Examples and tutorials coming soon. + +## Related Resources + +- [Session Insights](/openhands/usage/product-guides/session-insights) +- [Troubleshooting](/openhands/usage/troubleshooting/troubleshooting) diff --git a/openhands/usage/use-cases/spark-migrations.mdx b/openhands/usage/use-cases/spark-migrations.mdx new file mode 100644 index 00000000..a233b8af --- /dev/null +++ b/openhands/usage/use-cases/spark-migrations.mdx @@ -0,0 +1,36 @@ +--- +title: TODO-Spark Migrations +description: Migrating Apache Spark applications with OpenHands +--- + +# TODO-Spark Migrations + +## Overview + +Content coming soon. This page will cover how to use OpenHands to migrate and modernize Apache Spark applications. + +## Key Topics + +### Migration Scenarios +- Spark version upgrades +- Migration from other big data frameworks +- Cloud platform migrations + +### Code Transformation +- API updates +- Performance optimization +- Best practices application + +### Testing and Validation +- Job testing +- Performance benchmarking +- Data validation + +## Examples + +Examples and tutorials coming soon. + +## Related Resources + +- [Repository Setup](/openhands/usage/customization/repository) +- [Key Features](/openhands/usage/key-features) diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx new file mode 100644 index 00000000..e4b9a482 --- /dev/null +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -0,0 +1,36 @@ +--- +title: TODO-Vulnerability Remediation +description: Using OpenHands to identify and fix security vulnerabilities in your codebase +--- + +# TODO-Vulnerability Remediation + +## Overview + +Content coming soon. This page will cover how to use OpenHands for automated vulnerability detection and remediation. + +## Key Topics + +### Identifying Vulnerabilities +- Security scanning integration +- Vulnerability detection workflows +- Common vulnerability patterns + +### Automated Remediation +- Applying security patches +- Dependency updates for security fixes +- Code-level vulnerability fixes + +### Best Practices +- Security testing +- Validation approaches +- Continuous monitoring + +## Examples + +Examples and tutorials coming soon. + +## Related Resources + +- [Security Admin](/openhands/usage/admin/security) +- [Dependency Upgrades](/openhands/usage/use-cases/dependency-upgrades) From 8eebf155ab444b412882b60ba891f0761be97d18 Mon Sep 17 00:00:00 2001 From: jpelletier1 <44589723+jpelletier1@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:44:35 -0500 Subject: [PATCH 02/19] Added content to TODO pages. --- docs.json | 5 +- openhands/usage/admin/billing.mdx | 78 --- openhands/usage/admin/security.mdx | 76 --- .../good-vs-bad-instructions.mdx | 373 +++++++++++++- .../essential-guidelines/sdlc-integration.mdx | 443 ++++++++++++++++- .../when-to-use-openhands.mdx | 238 ++++++++- openhands/usage/get-started/tutorials.mdx | 455 ++++++++++++++++- .../usage/product-guides/session-insights.mdx | 44 -- .../usage/use-cases/cobol-modernization.mdx | 280 ++++++++++- openhands/usage/use-cases/code-review.mdx | 409 +++++++++++++++- .../usage/use-cases/dependency-upgrades.mdx | 412 +++++++++++++++- openhands/usage/use-cases/incident-triage.mdx | 429 +++++++++++++++- .../usage/use-cases/spark-migrations.mdx | 391 ++++++++++++++- .../use-cases/vulnerability-remediation.mdx | 460 +++++++++++++++++- 14 files changed, 3766 insertions(+), 327 deletions(-) delete mode 100644 openhands/usage/admin/billing.mdx delete mode 100644 openhands/usage/admin/security.mdx delete mode 100644 openhands/usage/product-guides/session-insights.mdx diff --git a/docs.json b/docs.json index a0b77e13..c9e80b67 100644 --- a/docs.json +++ b/docs.json @@ -62,7 +62,6 @@ ] }, "openhands/usage/settings/secrets-settings", - "openhands/usage/product-guides/session-insights", { "group": "Settings", "pages": [ @@ -78,9 +77,7 @@ "group": "OpenHands Cloud", "pages": [ "openhands/usage/cloud/openhands-cloud", - "openhands/usage/cloud/cloud-ui", - "openhands/usage/admin/security", - "openhands/usage/admin/billing" + "openhands/usage/cloud/cloud-ui" ] } ] diff --git a/openhands/usage/admin/billing.mdx b/openhands/usage/admin/billing.mdx deleted file mode 100644 index 6835f2db..00000000 --- a/openhands/usage/admin/billing.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: TODO-Billing -description: Usage tracking and billing for OpenHands Cloud ---- - -# TODO-Billing - -## Usage Tracking for OpenHands Cloud - -### Understanding Usage Metrics - -### Billable Activities - -### Usage Dashboard - -### Usage Reports - -## Credit Management - -### Credit System Overview - -### Purchasing Credits - -### Credit Balance - -### Credit Expiration - -### Auto-Renewal - -## Billing Plans - -### Free Tier - -### Individual Plans - -### Team Plans - -### Enterprise Plans - -## Payment Methods - -### Supported Payment Options - -### Adding Payment Methods - -### Updating Payment Information - -### Payment Security - -## Invoicing - -### Invoice Generation - -### Downloading Invoices - -### Invoice History - -### Tax Information - -## Cost Optimization - -### Monitoring Usage - -### Setting Budgets - -### Usage Alerts - -### Cost-Saving Tips - -## Billing Support - -### Common Billing Questions - -### Refund Policy - -### Billing Disputes - -### Contact Billing Support diff --git a/openhands/usage/admin/security.mdx b/openhands/usage/admin/security.mdx deleted file mode 100644 index 446b66bd..00000000 --- a/openhands/usage/admin/security.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: TODO-Security -description: Comprehensive security overview for OpenHands ---- - -# TODO-Security - -## Comprehensive Security Overview - -### Security Architecture - -### Data Protection - -### Infrastructure Security - -### Network Security - -## Privacy & Intellectual Property - -### Data Privacy - -### Code Privacy - -### Intellectual Property Protection - -### Data Retention Policies - -## User Best Practices - -### Secure Configuration - -### Authentication Best Practices - -### Secret Management - -### Access Control - -## Third-Party Audits - -### Security Certifications - -### Compliance Standards - -### Audit Reports - -### Penetration Testing - -## Security Features - -### Encryption - -#### Data in Transit - -#### Data at Rest - -### Access Controls - -### Audit Logging - -### Vulnerability Management - -## Incident Response - -### Reporting Security Issues - -### Incident Response Process - -### Security Updates - -## Compliance - -### GDPR Compliance - -### SOC 2 Compliance - -### Other Certifications diff --git a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx index dd875b8e..0fe82d8a 100644 --- a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx +++ b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx @@ -3,7 +3,7 @@ title: TODO-Good vs. Bad Instructions description: Learn how to write effective instructions for OpenHands --- -# TODO-Good vs. Bad Instructions +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 @@ -11,52 +11,423 @@ description: Learn how to write effective instructions for OpenHands #### 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 index fe81b71f..92931852 100644 --- a/openhands/usage/essential-guidelines/sdlc-integration.mdx +++ b/openhands/usage/essential-guidelines/sdlc-integration.mdx @@ -3,54 +3,495 @@ title: TODO-OpenHands in Your SDLC description: How OpenHands fits into your software development lifecycle --- -# TODO-OpenHands in Your SDLC +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 index 05bdf478..69816d66 100644 --- a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx +++ b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx @@ -3,44 +3,280 @@ title: TODO-When to Use OpenHands description: Guidance on when OpenHands is the right tool for your task --- -# TODO-When to Use OpenHands +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 index fa355e66..8ef4d2d9 100644 --- a/openhands/usage/get-started/tutorials.mdx +++ b/openhands/usage/get-started/tutorials.mdx @@ -3,28 +3,457 @@ title: TODO-Tutorial Library description: Centralized hub for OpenHands tutorials and examples --- -# TODO-Tutorial Library +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: Testing, Data Analysis, Web Scraping, etc. +## Categories Overview -### Task Complexity Guidance +| 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 | -### Best Use Cases +## Task Complexity Guidance -### Example Tutorials by Category +Before starting, assess your task's complexity: -#### Testing +**Simple tasks** (5-15 minutes): +- Single file changes +- Clear, well-defined requirements +- Existing patterns to follow -#### Data Analysis +**Medium tasks** (15-45 minutes): +- Multiple file changes +- Some discovery required +- Integration with existing code -#### Web Scraping +**Complex tasks** (45+ minutes): +- Architectural changes +- Multiple components +- Requires iteration -#### Code Review + +Start with simpler tutorials to build familiarity with OpenHands before tackling complex tasks. + -#### Bug Fixing +## Best Use Cases -#### Feature Development +OpenHands excels at: -### Getting Started with Tutorials +- **Repetitive tasks**: Boilerplate code, test generation +- **Pattern application**: Following established conventions +- **Analysis**: Code review, debugging, documentation +- **Exploration**: Understanding new codebases -### Contributing Tutorials +## 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 + +#### 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 + +#### 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. +``` + +--- + +## Getting Started with Tutorials + +### Step 1: Choose the Right Tutorial + +Match your task to a tutorial: +- What type of work are you doing? +- What's the complexity level? +- Do you have similar patterns in your codebase? + +### Step 2: Prepare Your Repository + +Before starting: +1. Ensure your code builds and tests pass +2. Update AGENTS.md with relevant patterns +3. Commit any pending changes +4. Have clear success criteria + +### Step 3: Customize the Prompt + +Adapt tutorial prompts to your needs: +- Replace file paths with your actual paths +- Update technology references (frameworks, libraries) +- Add project-specific constraints +- Include examples from your codebase + +### Step 4: Iterate if Needed + +If the first attempt isn't perfect: +1. Review what OpenHands produced +2. Identify gaps or misunderstandings +3. Provide clarifying instructions +4. Build on the previous work + +## 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/product-guides/session-insights.mdx b/openhands/usage/product-guides/session-insights.mdx deleted file mode 100644 index 7bd28032..00000000 --- a/openhands/usage/product-guides/session-insights.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: TODO-Session Insights -description: Analyze and improve your OpenHands sessions ---- - -# TODO-Session Insights - -## How to Analyze Session Performance - -### Understanding Session Metrics - -### Key Performance Indicators - -### Success Criteria - -### Common Patterns - -## Feedback Loops and Improvement Suggestions - -### Collecting Feedback - -### Analyzing Session Results - -### Identifying Areas for Improvement - -### Implementing Improvements - -## Session Analytics Dashboard - -### Overview Metrics - -### Detailed Analytics - -### Historical Trends - -## Best Practices for Session Management - -### Planning Sessions - -### Monitoring Progress - -### Post-Session Review - -### Continuous Improvement diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 35103cc7..6880f321 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -3,34 +3,278 @@ title: TODO-COBOL Modernization description: Modernizing legacy COBOL systems with OpenHands --- -# TODO-COBOL Modernization +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. ## Overview -Content coming soon. This page will cover how to use OpenHands to modernize legacy COBOL codebases. +COBOL modernization with OpenHands focuses on three key areas: -## Key Topics +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 -### Code Analysis -- COBOL code understanding -- Business logic extraction -- Dependency mapping + +COBOL modernization is a complex undertaking. OpenHands works best as an assistant to experienced developers rather than a fully autonomous solution for large-scale migrations. + -### Modernization Strategies -- Translation to modern languages -- Refactoring approaches -- Incremental migration +## Code Analysis -### Testing and Validation -- Behavior preservation -- Regression testing -- Output validation +### COBOL Code Understanding + +OpenHands can help you understand COBOL programs by: + +- **Explaining program structure**: Identifying divisions, sections, and paragraphs +- **Documenting data definitions**: Parsing WORKING-STORAGE and FILE SECTION entries +- **Tracing program flow**: Following PERFORM statements and GO TO branches +- **Identifying business rules**: Extracting logic from PROCEDURE DIVISION code + +**Example prompt:** +``` +Analyze the COBOL program in src/CUSTMGMT.cbl and explain: +1. What business function does this program perform? +2. What are the main data structures used? +3. What external files or databases does it interact with? +4. Create a flowchart of the main processing logic. +``` + +### Business Logic Extraction + +Extract and document business rules embedded in COBOL: + +- **Calculation rules**: Interest calculations, pricing formulas, fee structures +- **Validation rules**: Data validation, business constraint checking +- **Decision logic**: Complex IF/EVALUATE structures and their conditions +- **Processing sequences**: Order of operations and dependencies + +**Example prompt:** +``` +Extract all business rules from LOANPROC.cbl related to: +- Interest rate calculations +- Payment scheduling +- Late fee assessment + +Document each rule with: +1. The COBOL code implementing it +2. A plain English description +3. Any edge cases or special conditions +``` + +### Dependency Mapping + +Understand how COBOL programs interact: + +- **Program calls**: CALL statements and their parameters +- **Copybook usage**: Shared data definitions across programs +- **File dependencies**: Which programs read/write which files +- **Database access**: DB2, IMS, or VSAM interactions + +**Example prompt:** +``` +Create a dependency map for the programs in the ACCTG folder: +1. Which programs call which other programs? +2. Which copybooks are used by each program? +3. Which files are shared between programs? +4. Generate a visual diagram of these dependencies. +``` + +## Modernization Strategies + +### Translation to Modern Languages + +OpenHands can assist with translating COBOL to modern languages: + + + + **Best for**: Enterprise applications, existing Java ecosystems + + ``` + Translate CUSTMGMT.cbl to Java, following these guidelines: + - Use Java 17 features where appropriate + - Create separate classes for data structures and business logic + - Use BigDecimal for all monetary calculations + - Add JavaDoc comments explaining the original COBOL structure + - Create a mapping document showing COBOL to Java correspondence + ``` + + + **Best for**: Data processing, analytics, rapid prototyping + + ``` + Translate RPTGEN.cbl to Python, following these guidelines: + - Use Python 3.11+ features + - Use dataclasses for record structures + - Use Decimal for monetary calculations + - Preserve the original program's logic flow + - Add type hints throughout + ``` + + + **Best for**: Windows environments, .NET ecosystems + + ``` + Translate INVPROC.cbl to C#, following these guidelines: + - Target .NET 8 + - Use records for data structures + - Use decimal for monetary values + - Follow Microsoft naming conventions + - Add XML documentation comments + ``` + + + +### Refactoring Approaches + +Different approaches for different needs: + +| Approach | Description | Best For | +|----------|-------------|----------| +| Lift and shift | Direct translation preserving structure | Quick migration, minimal risk | +| Restructure | Translate and improve code organization | Medium-term maintainability | +| Re-architect | Redesign using modern patterns | Long-term strategic value | + +**Incremental refactoring prompt:** +``` +Refactor ORDPROC.cbl incrementally: +1. First, translate to Java maintaining the original structure +2. Then, extract the validation logic into a separate ValidationService class +3. Finally, refactor the main processing into smaller, testable methods + +At each stage, provide tests to verify behavior hasn't changed. +``` + +### Incremental Migration + +Migrate piece by piece to reduce risk: + +1. **Start with utilities**: Begin with standalone utility programs +2. **Create adapters**: Build bridges between COBOL and modern code +3. **Migrate by function**: Move one business function at a time +4. **Maintain parallel operation**: Run old and new systems side by side + +**Example prompt:** +``` +Create an incremental migration plan for the billing system: +1. Identify which programs can be migrated independently +2. Design an adapter layer for programs that need to call both COBOL and Java +3. Prioritize programs by risk and business value +4. Create a timeline with milestones and validation checkpoints +``` + +## Testing and Validation + +### Behavior Preservation + +Ensure modernized code produces identical results: + +- **Golden file testing**: Capture COBOL outputs as test expectations +- **Comparison testing**: Run both versions with identical inputs +- **Edge case coverage**: Test boundary conditions and error paths +- **Performance validation**: Verify acceptable performance characteristics + +**Example prompt:** +``` +Create a test suite to validate the Java translation of PAYROLL.cbl: +1. Extract 100 representative test cases from production data +2. Run both COBOL and Java versions with these inputs +3. Compare outputs field by field +4. Generate a report of any discrepancies +``` + +### Regression Testing + +Build comprehensive regression test suites: + +``` +Create a regression test suite for the translated CUSTMGMT program: +1. Unit tests for each business rule extracted earlier +2. Integration tests for file I/O operations +3. End-to-end tests for complete transaction processing +4. Performance benchmarks comparing to COBOL baseline +``` + +### Output Validation + +Validate that modernized code produces correct output: + +- **Field-level comparison**: Match every output field +- **Format verification**: Ensure reports and files match expected formats +- **Decimal precision**: Verify monetary calculations are exact +- **Date handling**: Confirm date conversions are correct + +## Best Practices + +### Effective Prompts for COBOL Work + +- **Provide context**: Include relevant copybooks and called programs +- **Specify standards**: Define your target coding standards +- **Request documentation**: Ask for mapping documents alongside translations +- **Iterate incrementally**: Translate and validate in small chunks + +### Common Pitfalls to Avoid + + +- **Don't translate everything at once**: Large batch translations are error-prone +- **Don't ignore packed decimal handling**: Ensure proper numeric conversions +- **Don't skip testing**: Every translation needs validation +- **Don't lose business knowledge**: Document rules before translating + + +### Recommended Workflow + +1. **Document first**: Have OpenHands analyze and document the COBOL program +2. **Extract rules**: Identify and document all business rules +3. **Create tests**: Build test cases from the documentation +4. **Translate incrementally**: Convert one section at a time +5. **Validate continuously**: Run tests after each translation step ## Examples -Examples and tutorials coming soon. +### Analyzing a COBOL Program + +``` +I have a COBOL program that calculates insurance premiums. +Please analyze PREMIUM.cbl and: + +1. Identify all the rating factors used in the calculation +2. Document the premium calculation formula +3. List any tables or external data referenced +4. Explain any special handling for different policy types +``` + +### Translating to Java + +``` +Translate the ACCTBAL.cbl program to Java: + +- Use Spring Boot as the framework +- Implement the file I/O using Java NIO +- Convert the indexed file access to JPA repository calls +- Preserve all decimal precision for monetary amounts +- Add comprehensive logging +- Create unit tests for each method +``` + +### Creating a Migration Plan + +``` +Create a migration plan for our accounts receivable system: + +Programs involved: +- ARMASTER.cbl (master file maintenance) +- ARINVOICE.cbl (invoice processing) +- ARPAYMENT.cbl (payment processing) +- ARAGING.cbl (aging report) + +Consider: +1. Dependencies between programs +2. Risk level of each program +3. Testing requirements +4. Recommended migration sequence +5. Rollback strategy +``` ## Related Resources -- [Repository Setup](/openhands/usage/customization/repository) -- [Key Features](/openhands/usage/key-features) +- [Repository Setup](/openhands/usage/customization/repository) - Configure your COBOL 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/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 1dfc87bf..1e9ca0a2 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -3,35 +3,406 @@ title: TODO-Code Review description: Leveraging OpenHands for automated and assisted code review --- -# TODO-Code Review +Code review is essential for maintaining code quality, sharing knowledge, and catching bugs before they reach production. OpenHands can assist with code reviews by analyzing changes, identifying potential issues, and suggesting improvements. ## Overview -Content coming soon. This page will cover how to use OpenHands to enhance your code review process. +OpenHands enhances your code review process by: -## Key Topics +- **Automated analysis**: Detecting bugs, security issues, and code smells +- **Standards enforcement**: Checking adherence to coding guidelines +- **Improvement suggestions**: Recommending better patterns and practices +- **Documentation**: Generating summaries and explanations of changes -### Automated Code Review -- Code quality analysis -- Style and standards enforcement -- Bug detection +## Automated Code Review -### Review Assistance -- Generating review comments -- Identifying potential issues -- Suggesting improvements +### Code Quality Analysis -### Integration -- GitHub pull request integration -- GitLab merge request integration -- CI/CD pipeline integration +OpenHands can analyze code changes for quality issues: + +``` +Review the changes in this pull request for code quality: + +1. Identify any code smells (long methods, deep nesting, etc.) +2. Check for proper error handling +3. Verify logging is appropriate and consistent +4. Look for potential memory leaks or resource handling issues +5. Assess test coverage of the changes +6. Rate overall code quality and explain your assessment +``` + +**What OpenHands checks for:** + +| Category | Issues Detected | +|----------|----------------| +| Complexity | Long methods, deep nesting, high cyclomatic complexity | +| Maintainability | Code duplication, unclear naming, missing documentation | +| Reliability | Null pointer risks, unhandled exceptions, race conditions | +| Performance | N+1 queries, unnecessary allocations, inefficient algorithms | + +### Style and Standards Enforcement + +Ensure code follows your team's standards: + +``` +Review this PR against our coding standards: + +Standards document: docs/CODING_STANDARDS.md + +Check for: +1. Naming convention compliance +2. File organization +3. Import ordering +4. Comment formatting +5. Consistent spacing and indentation +6. Required documentation presence +``` + +**Example findings:** + +```python +# Issue: Function name doesn't follow snake_case convention +def processUserData(data): # Should be: process_user_data + pass + +# Issue: Missing docstring for public function +def calculate_total(items): + # Add: """Calculate the total price of all items.""" + return sum(item.price for item in items) +``` + +### Bug Detection + +Identify potential bugs before they ship: + +``` +Analyze the code changes for potential bugs: + +1. Logic errors and edge cases +2. Off-by-one errors +3. Null/undefined handling +4. Type mismatches +5. Concurrency issues +6. Resource cleanup problems + +Provide specific line numbers and explanations for each issue found. +``` + +**Common bug patterns detected:** + + + + ```python + # Bug: Inverted condition + if user.is_active: + raise PermissionError("User is inactive") # Wrong! + + # Bug: Missing boundary check + def get_item(index): + return items[index] # No bounds checking + ``` + + + ```python + # Bug: File not closed on exception + def read_config(): + f = open("config.json") + data = json.load(f) # If this fails, file stays open + f.close() + return data + + # Fixed: + def read_config(): + with open("config.json") as f: + return json.load(f) + ``` + + + ```python + # Bug: Race condition + if key not in cache: + cache[key] = expensive_computation() # Another thread may have added it + return cache[key] + + # Fixed: Use setdefault or proper locking + ``` + + + +## Review Assistance + +### Generating Review Comments + +Get detailed review comments for a PR: + +``` +Generate code review comments for this pull request: + +For each issue found, provide: +1. The file and line number +2. The severity (critical, major, minor, suggestion) +3. A clear explanation of the issue +4. A suggested fix with code example + +Format the output as GitHub review comments. +``` + +**Example output:** + +``` +### src/api/users.py, line 45 +**Severity**: Major + +**Issue**: SQL injection vulnerability + +The user input is interpolated directly into the SQL query without sanitization. + +**Current code:** +query = f"SELECT * FROM users WHERE id = {user_id}" + +**Suggested fix:** +query = "SELECT * FROM users WHERE id = %s" +cursor.execute(query, (user_id,)) +``` + +### Identifying Potential Issues + +Proactively find issues that might cause problems: + +``` +Review this PR and identify potential issues: + +Categories to check: +1. Security vulnerabilities +2. Performance bottlenecks +3. Backwards compatibility breaks +4. Missing error handling +5. Test coverage gaps +6. Documentation needs + +Rank issues by risk and effort to fix. +``` + +### Suggesting Improvements + +Get suggestions for making code better: + +``` +Suggest improvements for the code in this PR: + +Focus on: +1. Cleaner, more idiomatic code +2. Better abstractions +3. Improved readability +4. Performance optimizations +5. More comprehensive testing +6. Enhanced documentation + +For each suggestion, explain the benefit and show before/after code. +``` + +**Example suggestion:** + +```python +# Before: Nested conditionals +def process_order(order): + if order.is_valid: + if order.payment_confirmed: + if order.items_in_stock: + return ship_order(order) + return None + +# After: Early returns +def process_order(order): + if not order.is_valid: + return None + if not order.payment_confirmed: + return None + if not order.items_in_stock: + return None + return ship_order(order) +``` + +## Integration + +### GitHub Pull Request Integration + +OpenHands integrates with GitHub for automated PR reviews: + +1. **Install the GitHub App**: See [GitHub Integration](/openhands/usage/cloud/github-installation) +2. **Configure auto-review**: Enable automatic review on PR creation +3. **Trigger manual reviews**: Comment `@openhands review` on any PR + +**Automatic review workflow:** + +```yaml +# .github/workflows/openhands-review.yml +name: OpenHands Code Review +on: + pull_request: + types: [opened, synchronize] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: openhands/review-action@v1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + review-type: comprehensive +``` + +### GitLab Merge Request Integration + +For GitLab users: + +1. **Install the GitLab integration**: See [GitLab Integration](/openhands/usage/cloud/gitlab-installation) +2. **Configure webhook triggers**: Enable review on MR creation +3. **Manual trigger**: Comment `/openhands review` on any MR + +### CI/CD Pipeline Integration + +Add code review to your CI/CD pipeline: + + + + ```yaml + - name: OpenHands Review + uses: openhands/review-action@v1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + fail-on: critical # Fail CI if critical issues found + ``` + + + ```yaml + code_review: + stage: review + script: + - openhands review --format=gitlab + allow_failure: false + ``` + + + ```bash + # Run OpenHands review and output results + openhands review \ + --base-branch main \ + --format json \ + --output review-results.json + + # Fail if critical issues found + if jq -e '.critical_count > 0' review-results.json; then + exit 1 + fi + ``` + + + +## Best Practices + +### Effective Review Prompts + +Write prompts that get useful reviews: + +``` +Review this PR with focus on: +- Security: We handle user PII in this code +- Performance: This runs in a hot path (1000+ calls/sec) +- Backwards compatibility: This is a public API + +Context: +- This is a Python 3.11 project using FastAPI +- We follow PEP 8 and Google style docstrings +- Database is PostgreSQL with SQLAlchemy ORM + +Ignore: +- Formatting issues (handled by pre-commit) +- Import ordering (handled by isort) +``` + +### Combining Human and AI Review + +Get the best of both worlds: + +1. **First pass: OpenHands** + - Automated checks for common issues + - Consistency verification + - Initial quality assessment + +2. **Second pass: Human reviewer** + - Architecture and design decisions + - Business logic correctness + - Knowledge transfer and mentoring + +3. **Final pass: Author response** + - Address all feedback + - Explain any disagreements + - Request re-review if needed + +### Review Scope Guidelines + +| Change Size | Recommended Approach | +|-------------|---------------------| +| Small (under 50 lines) | Full automated review | +| Medium (50-200 lines) | Automated + focused human review | +| Large (over 200 lines) | Split PR or section-by-section review | +| Refactoring | Focus on behavior preservation | +| New feature | Focus on design and test coverage | ## Examples -Examples and tutorials coming soon. +### Security-Focused Review + +``` +Perform a security review of this PR: + +1. Check for injection vulnerabilities (SQL, XSS, command injection) +2. Verify authentication and authorization checks +3. Look for sensitive data exposure +4. Check cryptographic implementations +5. Verify input validation +6. Review error messages for information leakage + +Rate each finding by CVSS severity and provide remediation steps. +``` + +### Performance Review + +``` +Review this PR for performance: + +Context: This code runs in our order processing pipeline +handling 10,000 orders/minute. + +Check for: +1. Database query efficiency (N+1, missing indexes) +2. Memory allocations in loops +3. Blocking operations that could be async +4. Caching opportunities +5. Algorithm complexity + +Estimate the performance impact of any issues found. +``` + +### API Review + +``` +Review this API change: + +Check for: +1. RESTful design principles +2. Consistent naming and URL structure +3. Appropriate HTTP methods and status codes +4. Request/response validation +5. Error handling and error messages +6. API documentation completeness +7. Backwards compatibility with v1 clients +``` ## Related Resources -- [GitHub Integration](/openhands/usage/cloud/github-installation) -- [GitLab Integration](/openhands/usage/cloud/gitlab-installation) -- [Integrations Overview](/openhands/usage/settings/integrations-settings) +- [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration +- [GitLab Integration](/openhands/usage/cloud/gitlab-installation) - Set up GitLab integration +- [Integrations Overview](/openhands/usage/settings/integrations-settings) - All available integrations +- [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 index a7a5ec62..e92a61a0 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -3,34 +3,410 @@ title: TODO-Dependency Upgrades description: Automating dependency updates and upgrades with OpenHands --- -# TODO-Dependency Upgrades +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 -Content coming soon. This page will cover how to use OpenHands to automate dependency upgrades and manage breaking changes. +OpenHands helps with dependency management by: -## Key Topics +- **Analyzing dependencies**: Identifying outdated packages and security vulnerabilities +- **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 -- Security vulnerability scanning -- Compatibility checking +## Dependency Analysis -### Automated Upgrades -- Version updates -- Breaking change handling -- Code adaptation +### Identifying Outdated Dependencies -### Testing and Validation -- Automated test execution -- Integration testing -- Regression detection +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 Vulnerability Scanning + +Identify security issues in your dependencies: + +``` +Scan this project for dependency vulnerabilities: + +1. Run vulnerability scan (npm audit, pip-audit, etc.) +2. List all vulnerabilities by severity +3. For each vulnerability: + - Describe the risk + - Show affected code paths + - Recommend remediation +4. Create a prioritized fix plan +``` + +**Vulnerability report example:** + +``` +## Critical Vulnerabilities + +### CVE-2023-12345 - Prototype Pollution in lodash +- **Severity**: Critical (9.8) +- **Package**: lodash < 4.17.21 +- **Your version**: 4.17.15 +- **Fix**: Upgrade to lodash@4.17.21 +- **Breaking changes**: None expected + +### CVE-2023-67890 - XSS in sanitize-html +- **Severity**: High (7.5) +- **Package**: sanitize-html < 2.7.1 +- **Your version**: 2.3.0 +- **Fix**: Upgrade to sanitize-html@2.7.1 +- **Breaking changes**: New sanitization rules may affect output +``` + +### 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 -Examples and tutorials coming soon. +### 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) -- [Security Admin](/openhands/usage/admin/security) +- [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities +- [Security](/openhands/usage/admin/security) - Security best practices +- [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 index 6559774b..a2ecefed 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -3,34 +3,427 @@ title: TODO-Incident Triage description: Using OpenHands to investigate and resolve production incidents --- -# TODO-Incident Triage +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). ## Overview -Content coming soon. This page will cover how to use OpenHands for rapid incident investigation and resolution. +OpenHands accelerates incident response by: -## Key Topics +- **Rapid log analysis**: Parse and understand large volumes of logs quickly +- **Error investigation**: Trace errors through stack traces and code +- **Root cause identification**: Connect symptoms to underlying issues +- **Fix generation**: Create and test fixes for identified problems -### Incident Investigation -- Log analysis -- Error tracking -- Root cause analysis + +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. + -### Automated Diagnosis -- Pattern recognition -- Stack trace analysis -- System state investigation +## Incident Investigation -### Rapid Response -- Quick fix generation -- Hotfix deployment -- Documentation generation +### 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 | + +**Example prompt for multi-service logs:** + +``` +I have logs from three services during an incident: +- api-gateway.log (attached) +- user-service.log (attached) +- database-slow.log (attached) + +The incident: Users reported 504 timeout errors starting at 10:15 AM. + +Correlate events across these logs and identify: +1. The originating cause +2. How it propagated through services +3. Why it resulted in 504 errors +``` + +### Error Tracking + +Investigate errors from your error tracking system: + +``` +We have a Sentry alert for increased NullPointerException in the OrderService. + +Here's the stack trace and context: +[paste stack trace] + +Analyze this error: +1. What code path leads to this exception? +2. What input conditions could cause it? +3. When did this start occurring (check recent commits)? +4. How widespread is the impact? +``` + +### 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. +``` + +## Automated Diagnosis + +### Pattern Recognition + +OpenHands can recognize common incident patterns: + +``` +Analyze this error pattern and identify if it matches known issues: + +Error: Connection refused to redis:6379 +Frequency: 500 occurrences in last 10 minutes +Affected services: user-cache, session-store + +Check for: +1. Network connectivity issues +2. Redis server health +3. Connection pool exhaustion +4. Recent configuration changes +``` + +**Common patterns OpenHands identifies:** + +- **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 + +### 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? + ``` + + + +### System State Investigation + +Investigate the system state during an incident: + +``` +Help me investigate system state during the incident: + +Current observations: +- CPU: 95% (normally 30%) +- Memory: 85% (normally 60%) +- Disk I/O: 100% utilization +- Network: Normal + +Running processes (top output attached) +Open files (lsof output attached) +Network connections (netstat output attached) + +What's causing the high resource usage? +``` + +## Rapid Response + +### Quick Fix Generation + +Generate fixes for identified issues: + +``` +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 +``` + +**Example fix workflow:** + +``` +# Step 1: Identify the issue +The NullPointerException occurs because `user.getPreferences()` +can return null for new users. + +# Step 2: Generate the fix +```java +// Before +String theme = user.getPreferences().getTheme(); + +// After +String theme = Optional.ofNullable(user.getPreferences()) + .map(UserPreferences::getTheme) + .orElse(DEFAULT_THEME); +``` + +# Step 3: Generate the test +```java +@Test +void shouldUseDefaultThemeWhenPreferencesNull() { + User user = new User(); + user.setPreferences(null); + + String theme = userService.getTheme(user); + + assertEquals(DEFAULT_THEME, theme); +} +``` +``` + +### Hotfix Deployment + +Generate deployment commands for hotfixes: + +``` +Generate hotfix deployment steps for the OrderProcessor fix: + +Environment: Kubernetes on AWS EKS +Current version: v2.3.1 +Hotfix version: v2.3.2 + +Include: +1. Build commands +2. Image push commands +3. Rollout commands +4. Verification steps +5. Rollback commands if needed +``` + +### Documentation Generation + +Document the incident for post-mortem: + +``` +Generate an incident report for the OrderProcessor outage: + +Timeline: +- 14:00: First errors reported +- 14:15: Incident declared +- 14:30: Root cause identified +- 14:45: Hotfix deployed +- 15:00: Service restored + +Include: +1. Executive summary +2. Timeline of events +3. Root cause analysis +4. Impact assessment +5. Remediation steps taken +6. Follow-up action items +``` + +## Best Practices + +### Effective Investigation Prompts + +Provide context for faster diagnosis: + +``` +Investigate this production incident: + +Service: payment-gateway +Environment: production-us-east-1 +Incident start: 2024-01-15 14:32 UTC +Severity: P1 (customer-impacting) + +Symptoms: +- 30% of payment requests failing +- Error: "Transaction timeout after 30s" +- Affected: All payment methods + +Recent changes: +- v3.2.1 deployed at 14:00 (30 min before incident) +- Database maintenance window ended at 14:30 + +Available data: +- Application logs (CloudWatch) +- APM traces (Datadog) +- Database metrics (RDS dashboard) +``` + +### 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 + ## Examples -Examples and tutorials coming soon. +### Database Performance Incident + +``` +Investigate a database performance incident: + +Symptoms: +- API latency increased from 100ms to 5s +- Database CPU at 100% +- Connection pool exhausted + +Data available: +- Slow query log (attached) +- APM traces showing database calls +- Recent schema migration completed 2 hours ago + +Find the problematic query and suggest a fix. +``` + +### Memory Leak Investigation + +``` +Investigate a memory leak in our Node.js application: + +Observations: +- Memory usage grows 100MB/hour +- Restarts temporarily fix the issue +- Started after v2.1.0 deployment + +Available: +- Heap snapshot from before restart +- Git diff of v2.0.9 to v2.1.0 +- Memory usage graphs + +Identify the leak and suggest a fix. +``` + +### Cascading Failure Analysis + +``` +Analyze this cascading failure: + +Timeline: +- 10:00: Redis primary failed over to replica +- 10:01: Cache miss rate increased 10x +- 10:02: Database connections exhausted +- 10:03: API gateway started returning 503 +- 10:05: All services unavailable + +Help me understand: +1. Why did a Redis failover cause total outage? +2. Where are the missing circuit breakers? +3. How do we prevent this in the future? +``` ## Related Resources -- [Session Insights](/openhands/usage/product-guides/session-insights) -- [Troubleshooting](/openhands/usage/troubleshooting/troubleshooting) +- [Session Insights](/openhands/usage/product-guides/session-insights) - Analyze session performance +- [Troubleshooting](/openhands/usage/troubleshooting/troubleshooting) - Common OpenHands issues +- [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 index a233b8af..b4c213be 100644 --- a/openhands/usage/use-cases/spark-migrations.mdx +++ b/openhands/usage/use-cases/spark-migrations.mdx @@ -3,34 +3,389 @@ title: TODO-Spark Migrations description: Migrating Apache Spark applications with OpenHands --- -# TODO-Spark Migrations +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 -Content coming soon. This page will cover how to use OpenHands to migrate and modernize Apache Spark applications. +OpenHands assists with Spark migrations in several ways: -## Key Topics +- **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 -- Migration from other big data frameworks -- Cloud platform migrations +## Migration Scenarios -### Code Transformation -- API updates -- Performance optimization -- Best practices application +### Spark Version Upgrades -### Testing and Validation -- Job testing -- Performance benchmarking -- Data validation +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 -Examples and tutorials coming soon. +### 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) -- [Key Features](/openhands/usage/key-features) +- [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 index e4b9a482..0c39160d 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -3,34 +3,458 @@ title: TODO-Vulnerability Remediation description: Using OpenHands to identify and fix security vulnerabilities in your codebase --- -# TODO-Vulnerability Remediation +Security vulnerabilities in your code can lead to data breaches, system compromises, and compliance failures. OpenHands can help you identify vulnerabilities, understand their impact, and implement secure fixes quickly and effectively. ## Overview -Content coming soon. This page will cover how to use OpenHands for automated vulnerability detection and remediation. +OpenHands assists with vulnerability remediation by: -## Key Topics +- **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 -### Identifying Vulnerabilities -- Security scanning integration -- Vulnerability detection workflows -- Common vulnerability patterns +## Identifying Vulnerabilities -### Automated Remediation -- Applying security patches -- Dependency updates for security fixes -- Code-level vulnerability fixes +### Security Scanning Integration -### Best Practices -- Security testing -- Validation approaches -- Continuous monitoring +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 +``` + +### Vulnerability Detection Workflows + +Ask OpenHands to scan for specific vulnerability types: + +``` +Scan this codebase for OWASP Top 10 vulnerabilities: + +1. Injection flaws (SQL, NoSQL, OS command, LDAP) +2. Broken authentication +3. Sensitive data exposure +4. XML external entities (XXE) +5. Broken access control +6. Security misconfiguration +7. Cross-site scripting (XSS) +8. Insecure deserialization +9. Using components with known vulnerabilities +10. Insufficient logging and monitoring + +Report findings with file locations and severity ratings. +``` + +### 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"` | + +**Detection prompt:** + +``` +Search this repository for: +1. Hardcoded passwords, API keys, or secrets +2. SQL queries using string concatenation +3. Shell commands using user input +4. File operations with unvalidated paths +5. HTML output without proper escaping + +List all findings with file locations. +``` + +## 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 + ``` + + + +### Dependency Updates for Security Fixes + +Address vulnerable dependencies: + +``` +We have CVE-2023-12345 affecting lodash < 4.17.21. + +1. Check our current lodash version +2. Identify all files importing lodash +3. Update to the patched version +4. Check for breaking changes +5. Run tests to verify nothing broke +6. Update package-lock.json +``` + +### 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) +``` + +## Best Practices + +### 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 +``` + +**Example test suite:** + +```python +import pytest + +class TestSQLInjectionPrevention: + def test_normal_query(self): + result = get_user(1) + assert result.id == 1 + + def test_injection_attempt_or(self): + # Should return no results, not all users + result = get_user("1 OR 1=1") + assert result is None + + def test_injection_attempt_union(self): + result = get_user("1 UNION SELECT * FROM passwords") + assert result is None + + def test_injection_attempt_comment(self): + result = get_user("1; DROP TABLE users; --") + # Table should still exist + assert User.query.count() > 0 +``` + +### Validation Approaches + +Verify your remediation is complete: + +``` +Validate that the XSS fix is effective: + +1. Test common XSS payloads: + - + - + - javascript:alert('xss') + - + +2. Test encoding bypass attempts: + - <script> + - \u003cscript\u003e + - %3Cscript%3E + +3. Test context-specific attacks: + - Attribute injection + - Event handler injection + - URL scheme injection + +4. Verify Content Security Policy is set +5. Confirm X-XSS-Protection header is present +``` + +### Continuous Monitoring + +Set up ongoing security monitoring: + +``` +Create a security monitoring workflow: + +1. Add SAST (Static Application Security Testing) to CI: + - Run on every pull request + - Block merge on critical findings + - Report all findings to security team + +2. Add dependency scanning: + - Check for vulnerable dependencies daily + - Create tickets for new vulnerabilities + - Auto-create PRs for safe updates + +3. Add secrets scanning: + - Pre-commit hook for secret detection + - Block commits containing secrets + - Alert on any secrets found in history + +4. Create security dashboard: + - Track vulnerability counts over time + - Monitor mean time to remediation + - Track security test coverage +``` + +## Vulnerability Categories + +### Injection Vulnerabilities + +``` +Audit this codebase for injection vulnerabilities: + +Check for: +1. SQL injection (parameterized queries?) +2. NoSQL injection (MongoDB query injection?) +3. Command injection (shell command building?) +4. LDAP injection (LDAP query construction?) +5. Expression Language injection (template injection?) +6. Header injection (CRLF in headers?) + +For each finding: +- Show the vulnerable code +- Explain the attack vector +- Provide the fix +- Add a regression test +``` + +### Authentication Issues + +``` +Review authentication implementation for vulnerabilities: + +Check for: +1. Weak password policies +2. Missing brute force protection +3. Session fixation vulnerabilities +4. Insecure password storage (not bcrypt/argon2?) +5. Missing multi-factor authentication +6. Insecure "remember me" implementation +7. Password reset vulnerabilities + +Provide recommendations for each issue found. +``` + +### Authorization Flaws + +``` +Audit authorization controls: + +Check for: +1. Broken access control (IDOR) +2. Missing function-level access control +3. Privilege escalation paths +4. JWT vulnerabilities (algorithm confusion, weak secrets) +5. OAuth misconfigurations +6. CORS misconfigurations + +Test each endpoint for unauthorized access. +``` + +### Data Exposure + +``` +Check for sensitive data exposure: + +1. Are secrets hardcoded anywhere? +2. Is sensitive data logged? +3. Is PII properly encrypted at rest? +4. Is data encrypted in transit (TLS)? +5. Are error messages leaking information? +6. Is sensitive data in URLs (logged by proxies)? +7. Are backups encrypted? + +List all findings with severity ratings. +``` ## Examples -Examples and tutorials coming soon. +### Critical Vulnerability Fix + +``` +We have a critical remote code execution vulnerability: + +File: src/api/upload.py +Issue: Arbitrary file upload allows code execution + +Current code: +def upload_file(file): + filename = file.filename + file.save(os.path.join(UPLOAD_DIR, filename)) + return {"message": "Upload successful"} + +Fix this vulnerability: +1. Validate file extension against whitelist +2. Sanitize filename (remove path traversal) +3. Generate random filename +4. Scan file content for malicious patterns +5. Store outside web root +6. Add proper error handling +``` + +### Comprehensive Security Audit + +``` +Perform a comprehensive security audit of our authentication system: + +Files to review: +- src/auth/login.py +- src/auth/session.py +- src/auth/password.py +- src/middleware/auth.py + +Check for: +1. OWASP Authentication Cheat Sheet compliance +2. Password storage best practices +3. Session management security +4. Brute force protection +5. Account lockout mechanisms +6. Secure cookie settings +7. CSRF protection + +Provide a report with findings and fixes. +``` + +### Automated Remediation 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 +``` ## Related Resources -- [Security Admin](/openhands/usage/admin/security) -- [Dependency Upgrades](/openhands/usage/use-cases/dependency-upgrades) +- [Security](/openhands/usage/admin/security) - Comprehensive security overview +- [Dependency Upgrades](/openhands/usage/use-cases/dependency-upgrades) - Updating vulnerable dependencies +- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts From 12678f5a08a6a11a819aa26638ed3e7a48d308bd Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 4 Feb 2026 16:13:36 +0000 Subject: [PATCH 03/19] Update Use Cases documentation pages - incident-triage.mdx: Add content based on Datadog debugging blog post - Features automated error analysis with OpenHands SDK - Includes GitHub Actions workflow for Datadog integration - Links to blog: https://openhands.dev/blog/debugging-production-issues-with-ai-agents-automating-datadog-error-analysis - cobol-modernization.mdx: Add content based on COBOL-to-Java refactoring blog post - Features iterative refinement approach with multiple agents - Includes code transformation examples (COBOL to Java) - Links to blog: https://openhands.dev/blog/20251218-cobol-to-java-refactoring - vulnerability-remediation.mdx: Add content based on vulnerability fixer documentation - Explains automated vulnerability remediation with AI agents - Links to example implementation at github.com/OpenHands/vulnerability-fixer - Covers integration with security scanners (Snyk, Dependabot, CodeQL) - dependency-upgrades.mdx: Remove redundant security scanning section - Links to Vulnerability Remediation page for security-related upgrades - Focuses on general dependency upgrade workflows Co-authored-by: openhands --- .../usage/use-cases/cobol-modernization.mdx | 203 +++++------ .../usage/use-cases/dependency-upgrades.mdx | 43 +-- openhands/usage/use-cases/incident-triage.mdx | 343 +++++------------- .../use-cases/vulnerability-remediation.mdx | 332 ++++------------- 4 files changed, 264 insertions(+), 657 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 6880f321..8f28ccf4 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -1,21 +1,106 @@ --- -title: TODO-COBOL Modernization +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 unique syntax making it difficult for human teams alone. + +AI is now achieving what armies of developers couldn't: automated code analysis, transformation, and verification at scale. + ## Overview +Simply converting COBOL syntax to Java isn't enough—the converted code needs to preserve business logic, follow modern language conventions, and be maintainable by modern development teams. + COBOL modernization with OpenHands focuses on three key areas: 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 - -COBOL modernization is a complex undertaking. OpenHands works best as an assistant to experienced developers rather than a fully autonomous solution for large-scale migrations. - +## Iterative Refinement Approach + +One effective method is an iterative refinement pattern using multiple agents in a feedback loop. The idea is simple: one agent does the work, another agent checks it, and if it's not good enough, the first agent tries again with the feedback. + +Here's what that looks like in code using the [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk): + +```python +while current_score < QUALITY_THRESHOLD and iteration < MAX_ITERATIONS: + # Refactoring agent converts COBOL to Java + refactoring_conversation.send_message(refactoring_prompt) + refactoring_conversation.run() + + # Critique 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) +``` + +The result is more than just code that runs—it's code that faithfully reproduces the original and meets your standards on quality and maintainability. + +### How It Works + +The **refactoring agent** receives instructions about conversion requirements: preserve business logic, use Java naming conventions, implement error handling, and add documentation. + +The **critique agent** evaluates each converted file on correctness, code quality, completeness, and best practices—producing a structured report with specific issues to address. + +If the result isn't up to your specified standard, the refactoring agent runs again with the critique feedback, making targeted improvements. + +### Example Transformation + +Here's a COBOL customer management program: + +```cobol +1000-MAIN-PROCESS. + DISPLAY "CUSTOMER MANAGEMENT SYSTEM" + EVALUATE TRUE + WHEN OP-ADD + PERFORM 2000-ADD-CUSTOMER + WHEN OP-UPDATE + PERFORM 3000-UPDATE-CUSTOMER + WHEN OP-DELETE + PERFORM 4000-DELETE-CUSTOMER + END-EVALUATE. +``` + +The agent converts this to idiomatic Java: + +```java +public class CustomerManagement { + public void mainProcess() { + System.out.println("CUSTOMER MANAGEMENT SYSTEM"); + switch (operation) { + case ADD -> addCustomer(); + case UPDATE -> updateCustomer(); + case DELETE -> deleteCustomer(); + default -> System.out.println("INVALID OPERATION"); + } + } +} +``` + +## 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. ## Code Analysis @@ -59,24 +144,6 @@ Document each rule with: 3. Any edge cases or special conditions ``` -### Dependency Mapping - -Understand how COBOL programs interact: - -- **Program calls**: CALL statements and their parameters -- **Copybook usage**: Shared data definitions across programs -- **File dependencies**: Which programs read/write which files -- **Database access**: DB2, IMS, or VSAM interactions - -**Example prompt:** -``` -Create a dependency map for the programs in the ACCTG folder: -1. Which programs call which other programs? -2. Which copybooks are used by each program? -3. Which files are shared between programs? -4. Generate a visual diagram of these dependencies. -``` - ## Modernization Strategies ### Translation to Modern Languages @@ -132,33 +199,11 @@ Different approaches for different needs: | Restructure | Translate and improve code organization | Medium-term maintainability | | Re-architect | Redesign using modern patterns | Long-term strategic value | -**Incremental refactoring prompt:** -``` -Refactor ORDPROC.cbl incrementally: -1. First, translate to Java maintaining the original structure -2. Then, extract the validation logic into a separate ValidationService class -3. Finally, refactor the main processing into smaller, testable methods - -At each stage, provide tests to verify behavior hasn't changed. -``` - -### Incremental Migration +## Scaling Up with the Large Codebase SDK -Migrate piece by piece to reduce risk: +The iterative refinement example works well for small to medium codebases. But enterprise COBOL systems can span millions of lines across thousands of programs, with complex interdependencies. -1. **Start with utilities**: Begin with standalone utility programs -2. **Create adapters**: Build bridges between COBOL and modern code -3. **Migrate by function**: Move one business function at a time -4. **Maintain parallel operation**: Run old and new systems side by side - -**Example prompt:** -``` -Create an incremental migration plan for the billing system: -1. Identify which programs can be migrated independently -2. Design an adapter layer for programs that need to call both COBOL and Java -3. Prioritize programs by risk and business value -4. Create a timeline with milestones and validation checkpoints -``` +For these large-scale modernization projects, the OpenHands Large Codebase SDK extends the iterative refinement pattern with specialized COBOL refactoring workflows that understand common mainframe patterns—CICS transactions, JCL jobs, VSAM file handling—and convert them to appropriate Java equivalents. ## Testing and Validation @@ -180,18 +225,6 @@ Create a test suite to validate the Java translation of PAYROLL.cbl: 4. Generate a report of any discrepancies ``` -### Regression Testing - -Build comprehensive regression test suites: - -``` -Create a regression test suite for the translated CUSTMGMT program: -1. Unit tests for each business rule extracted earlier -2. Integration tests for file I/O operations -3. End-to-end tests for complete transaction processing -4. Performance benchmarks comparing to COBOL baseline -``` - ### Output Validation Validate that modernized code produces correct output: @@ -227,54 +260,12 @@ Validate that modernized code produces correct output: 4. **Translate incrementally**: Convert one section at a time 5. **Validate continuously**: Run tests after each translation step -## Examples - -### Analyzing a COBOL Program - -``` -I have a COBOL program that calculates insurance premiums. -Please analyze PREMIUM.cbl and: - -1. Identify all the rating factors used in the calculation -2. Document the premium calculation formula -3. List any tables or external data referenced -4. Explain any special handling for different policy types -``` - -### Translating to Java - -``` -Translate the ACCTBAL.cbl program to Java: - -- Use Spring Boot as the framework -- Implement the file I/O using Java NIO -- Convert the indexed file access to JPA repository calls -- Preserve all decimal precision for monetary amounts -- Add comprehensive logging -- Create unit tests for each method -``` - -### Creating a Migration Plan - -``` -Create a migration plan for our accounts receivable system: - -Programs involved: -- ARMASTER.cbl (master file maintenance) -- ARINVOICE.cbl (invoice processing) -- ARPAYMENT.cbl (payment processing) -- ARAGING.cbl (aging report) - -Consider: -1. Dependencies between programs -2. Risk level of each program -3. Testing requirements -4. Recommended migration sequence -5. Rollback strategy -``` + +COBOL modernization is a complex undertaking. OpenHands works best as an assistant to experienced developers rather than a fully autonomous solution for large-scale migrations. + ## Related Resources -- [Repository Setup](/openhands/usage/customization/repository) - Configure your COBOL repository for OpenHands -- [Key Features](/openhands/usage/key-features) - OpenHands capabilities overview +- [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 index e92a61a0..d602b5ea 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -1,5 +1,5 @@ --- -title: TODO-Dependency Upgrades +title: Dependency Upgrades description: Automating dependency updates and upgrades with OpenHands --- @@ -9,7 +9,7 @@ Keeping dependencies up to date is essential for security, performance, and acce OpenHands helps with dependency management by: -- **Analyzing dependencies**: Identifying outdated packages and security vulnerabilities +- **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 @@ -39,41 +39,14 @@ Analyze the dependencies in this project and create a report: | express | 4.17.1 | 4.18.2 | Minor update | Low | | moment | 2.29.1 | 2.29.4 | Deprecated | Medium | -### Security Vulnerability Scanning +### Security-Related Dependency Upgrades -Identify security issues in your dependencies: +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: -``` -Scan this project for dependency vulnerabilities: - -1. Run vulnerability scan (npm audit, pip-audit, etc.) -2. List all vulnerabilities by severity -3. For each vulnerability: - - Describe the risk - - Show affected code paths - - Recommend remediation -4. Create a prioritized fix plan -``` - -**Vulnerability report example:** - -``` -## Critical Vulnerabilities - -### CVE-2023-12345 - Prototype Pollution in lodash -- **Severity**: Critical (9.8) -- **Package**: lodash < 4.17.21 -- **Your version**: 4.17.15 -- **Fix**: Upgrade to lodash@4.17.21 -- **Breaking changes**: None expected - -### CVE-2023-67890 - XSS in sanitize-html -- **Severity**: High (7.5) -- **Package**: sanitize-html < 2.7.1 -- **Your version**: 2.3.0 -- **Fix**: Upgrade to sanitize-html@2.7.1 -- **Breaking changes**: New sanitization rules may affect output -``` +- 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 diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index a2ecefed..a193aeb5 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -1,128 +1,100 @@ --- -title: TODO-Incident Triage +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 -OpenHands accelerates incident response by: +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. -- **Rapid log analysis**: Parse and understand large volumes of logs quickly -- **Error investigation**: Trace errors through stack traces and code -- **Root cause identification**: Connect symptoms to underlying issues -- **Fix generation**: Create and test fixes for identified problems +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. - -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. - +OpenHands accelerates incident response by: -## Incident Investigation +- **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 -### Log Analysis +## Automated Datadog Error Analysis -OpenHands can analyze logs to identify patterns and anomalies: +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. -``` -Analyze these application logs for the incident that occurred at 14:32 UTC: +### How It Works -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 -``` +[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. -**Log analysis capabilities:** +[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. -| 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 | +### Triggering Automated Debugging -**Example prompt for multi-service logs:** +The GitHub Actions workflow can be triggered in two ways: -``` -I have logs from three services during an incident: -- api-gateway.log (attached) -- user-service.log (attached) -- database-slow.log (attached) +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. -The incident: Users reported 504 timeout errors starting at 10:15 AM. +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. -Correlate events across these logs and identify: -1. The originating cause -2. How it propagated through services -3. Why it resulted in 504 errors -``` +### Automated Investigation Process -### Error Tracking +When the workflow runs, it automatically performs the following steps: -Investigate errors from your error tracking system: +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 -``` -We have a Sentry alert for increased NullPointerException in the OrderService. +The agent identifies the exact file and line number where errors originate, determines root causes, and provides specific recommendations for fixes. -Here's the stack trace and context: -[paste stack trace] + +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`. + -Analyze this error: -1. What code path leads to this exception? -2. What input conditions could cause it? -3. When did this start occurring (check recent commits)? -4. How widespread is the impact? -``` +## Setting Up the Workflow -### Root Cause Analysis +To set up automated Datadog debugging in your own repository: -Identify the underlying cause of an incident: +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 -``` -Perform root cause analysis for this incident: +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. -Symptoms: -- API response times increased 5x at 14:00 -- Error rate jumped from 0.1% to 15% -- Database CPU spiked to 100% +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. -Available data: -- Application metrics (Grafana dashboard attached) -- Recent deployments: v2.3.1 deployed at 13:45 -- Database slow query log (attached) +## Manual Incident Investigation -Identify the root cause using the 5 Whys technique. -``` - -## Automated Diagnosis +You can also use OpenHands directly to investigate incidents without the automated workflow. -### Pattern Recognition +### Log Analysis -OpenHands can recognize common incident patterns: +OpenHands can analyze logs to identify patterns and anomalies: ``` -Analyze this error pattern and identify if it matches known issues: - -Error: Connection refused to redis:6379 -Frequency: 500 occurrences in last 10 minutes -Affected services: user-cache, session-store +Analyze these application logs for the incident that occurred at 14:32 UTC: -Check for: -1. Network connectivity issues -2. Redis server health -3. Connection pool exhaustion -4. Recent configuration changes +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 ``` -**Common patterns OpenHands identifies:** +**Log analysis capabilities:** -- **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 +| 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 @@ -185,31 +157,39 @@ Analyze this stack trace from our production error: -### System State Investigation +### Root Cause Analysis -Investigate the system state during an incident: +Identify the underlying cause of an incident: ``` -Help me investigate system state during the incident: +Perform root cause analysis for this incident: -Current observations: -- CPU: 95% (normally 30%) -- Memory: 85% (normally 60%) -- Disk I/O: 100% utilization -- Network: Normal +Symptoms: +- API response times increased 5x at 14:00 +- Error rate jumped from 0.1% to 15% +- Database CPU spiked to 100% -Running processes (top output attached) -Open files (lsof output attached) -Network connections (netstat output attached) +Available data: +- Application metrics (Grafana dashboard attached) +- Recent deployments: v2.3.1 deployed at 13:45 +- Database slow query log (attached) -What's causing the high resource usage? +Identify the root cause using the 5 Whys technique. ``` -## Rapid Response +## Common Incident Patterns -### Quick Fix Generation +OpenHands can recognize and help diagnose these common patterns: -Generate fixes for identified issues: +- **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. @@ -222,109 +202,8 @@ Generate a fix that: 5. Is minimally invasive for a hotfix ``` -**Example fix workflow:** - -``` -# Step 1: Identify the issue -The NullPointerException occurs because `user.getPreferences()` -can return null for new users. - -# Step 2: Generate the fix -```java -// Before -String theme = user.getPreferences().getTheme(); - -// After -String theme = Optional.ofNullable(user.getPreferences()) - .map(UserPreferences::getTheme) - .orElse(DEFAULT_THEME); -``` - -# Step 3: Generate the test -```java -@Test -void shouldUseDefaultThemeWhenPreferencesNull() { - User user = new User(); - user.setPreferences(null); - - String theme = userService.getTheme(user); - - assertEquals(DEFAULT_THEME, theme); -} -``` -``` - -### Hotfix Deployment - -Generate deployment commands for hotfixes: - -``` -Generate hotfix deployment steps for the OrderProcessor fix: - -Environment: Kubernetes on AWS EKS -Current version: v2.3.1 -Hotfix version: v2.3.2 - -Include: -1. Build commands -2. Image push commands -3. Rollout commands -4. Verification steps -5. Rollback commands if needed -``` - -### Documentation Generation - -Document the incident for post-mortem: - -``` -Generate an incident report for the OrderProcessor outage: - -Timeline: -- 14:00: First errors reported -- 14:15: Incident declared -- 14:30: Root cause identified -- 14:45: Hotfix deployed -- 15:00: Service restored - -Include: -1. Executive summary -2. Timeline of events -3. Root cause analysis -4. Impact assessment -5. Remediation steps taken -6. Follow-up action items -``` - ## Best Practices -### Effective Investigation Prompts - -Provide context for faster diagnosis: - -``` -Investigate this production incident: - -Service: payment-gateway -Environment: production-us-east-1 -Incident start: 2024-01-15 14:32 UTC -Severity: P1 (customer-impacting) - -Symptoms: -- 30% of payment requests failing -- Error: "Transaction timeout after 30s" -- Affected: All payment methods - -Recent changes: -- v3.2.1 deployed at 14:00 (30 min before incident) -- Database maintenance window ended at 14:30 - -Available data: -- Application logs (CloudWatch) -- APM traces (Datadog) -- Database metrics (RDS dashboard) -``` - ### Investigation Checklist Use this checklist when investigating: @@ -366,64 +245,12 @@ Avoid these common incident response mistakes: - **Ignoring rollback**: Always have a rollback plan before deploying fixes -## Examples - -### Database Performance Incident - -``` -Investigate a database performance incident: - -Symptoms: -- API latency increased from 100ms to 5s -- Database CPU at 100% -- Connection pool exhausted - -Data available: -- Slow query log (attached) -- APM traces showing database calls -- Recent schema migration completed 2 hours ago - -Find the problematic query and suggest a fix. -``` - -### Memory Leak Investigation - -``` -Investigate a memory leak in our Node.js application: - -Observations: -- Memory usage grows 100MB/hour -- Restarts temporarily fix the issue -- Started after v2.1.0 deployment - -Available: -- Heap snapshot from before restart -- Git diff of v2.0.9 to v2.1.0 -- Memory usage graphs - -Identify the leak and suggest a fix. -``` - -### Cascading Failure Analysis - -``` -Analyze this cascading failure: - -Timeline: -- 10:00: Redis primary failed over to replica -- 10:01: Cache miss rate increased 10x -- 10:02: Database connections exhausted -- 10:03: API gateway started returning 503 -- 10:05: All services unavailable - -Help me understand: -1. Why did a Redis failover cause total outage? -2. Where are the missing circuit breakers? -3. How do we prevent this in the future? -``` + +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 -- [Session Insights](/openhands/usage/product-guides/session-insights) - Analyze session performance -- [Troubleshooting](/openhands/usage/troubleshooting/troubleshooting) - Common OpenHands issues +- [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/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index 0c39160d..39813dfd 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -1,11 +1,29 @@ --- -title: TODO-Vulnerability Remediation +title: Vulnerability Remediation description: Using OpenHands to identify and fix security vulnerabilities in your codebase --- -Security vulnerabilities in your code can lead to data breaches, system compromises, and compliance failures. OpenHands can help you identify vulnerabilities, understand their impact, and implement secure fixes quickly and effectively. +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. -## Overview +## 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: @@ -14,9 +32,41 @@ OpenHands assists with vulnerability remediation by: - **Implementing fixes**: Generating secure code to address vulnerabilities - **Validating remediation**: Verifying fixes are effective and complete -## Identifying Vulnerabilities +## 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 -### Security Scanning Integration +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: @@ -35,28 +85,7 @@ For each vulnerability: - Suggest a fix ``` -### Vulnerability Detection Workflows - -Ask OpenHands to scan for specific vulnerability types: - -``` -Scan this codebase for OWASP Top 10 vulnerabilities: - -1. Injection flaws (SQL, NoSQL, OS command, LDAP) -2. Broken authentication -3. Sensitive data exposure -4. XML external entities (XXE) -5. Broken access control -6. Security misconfiguration -7. Cross-site scripting (XSS) -8. Insecure deserialization -9. Using components with known vulnerabilities -10. Insufficient logging and monitoring - -Report findings with file locations and severity ratings. -``` - -### Common Vulnerability Patterns +## Common Vulnerability Patterns OpenHands can detect these common vulnerability patterns: @@ -68,19 +97,6 @@ OpenHands can detect these common vulnerability patterns: | Command Injection | Shell commands with user input | `os.system("ping " + hostname)` | | Hardcoded Secrets | Credentials in source code | `password = "admin123"` | -**Detection prompt:** - -``` -Search this repository for: -1. Hardcoded passwords, API keys, or secrets -2. SQL queries using string concatenation -3. Shell commands using user input -4. File operations with unvalidated paths -5. HTML output without proper escaping - -List all findings with file locations. -``` - ## Automated Remediation ### Applying Security Patches @@ -166,21 +182,6 @@ Fix identified vulnerabilities: -### Dependency Updates for Security Fixes - -Address vulnerable dependencies: - -``` -We have CVE-2023-12345 affecting lodash < 4.17.21. - -1. Check our current lodash version -2. Identify all files importing lodash -3. Update to the patched version -4. Check for breaking changes -5. Run tests to verify nothing broke -6. Update package-lock.json -``` - ### Code-Level Vulnerability Fixes Fix application-level security issues: @@ -216,9 +217,7 @@ def get_documents(user_id: int, current_user: User = Depends(get_current_user)): return db.get_documents(user_id) ``` -## Best Practices - -### Security Testing +## Security Testing Test your fixes thoroughly: @@ -235,206 +234,9 @@ Create security tests for the SQL injection fix: 5. Verify error handling doesn't leak information ``` -**Example test suite:** +## Automated Remediation Pipeline -```python -import pytest - -class TestSQLInjectionPrevention: - def test_normal_query(self): - result = get_user(1) - assert result.id == 1 - - def test_injection_attempt_or(self): - # Should return no results, not all users - result = get_user("1 OR 1=1") - assert result is None - - def test_injection_attempt_union(self): - result = get_user("1 UNION SELECT * FROM passwords") - assert result is None - - def test_injection_attempt_comment(self): - result = get_user("1; DROP TABLE users; --") - # Table should still exist - assert User.query.count() > 0 -``` - -### Validation Approaches - -Verify your remediation is complete: - -``` -Validate that the XSS fix is effective: - -1. Test common XSS payloads: - - - - - - javascript:alert('xss') - - - -2. Test encoding bypass attempts: - - <script> - - \u003cscript\u003e - - %3Cscript%3E - -3. Test context-specific attacks: - - Attribute injection - - Event handler injection - - URL scheme injection - -4. Verify Content Security Policy is set -5. Confirm X-XSS-Protection header is present -``` - -### Continuous Monitoring - -Set up ongoing security monitoring: - -``` -Create a security monitoring workflow: - -1. Add SAST (Static Application Security Testing) to CI: - - Run on every pull request - - Block merge on critical findings - - Report all findings to security team - -2. Add dependency scanning: - - Check for vulnerable dependencies daily - - Create tickets for new vulnerabilities - - Auto-create PRs for safe updates - -3. Add secrets scanning: - - Pre-commit hook for secret detection - - Block commits containing secrets - - Alert on any secrets found in history - -4. Create security dashboard: - - Track vulnerability counts over time - - Monitor mean time to remediation - - Track security test coverage -``` - -## Vulnerability Categories - -### Injection Vulnerabilities - -``` -Audit this codebase for injection vulnerabilities: - -Check for: -1. SQL injection (parameterized queries?) -2. NoSQL injection (MongoDB query injection?) -3. Command injection (shell command building?) -4. LDAP injection (LDAP query construction?) -5. Expression Language injection (template injection?) -6. Header injection (CRLF in headers?) - -For each finding: -- Show the vulnerable code -- Explain the attack vector -- Provide the fix -- Add a regression test -``` - -### Authentication Issues - -``` -Review authentication implementation for vulnerabilities: - -Check for: -1. Weak password policies -2. Missing brute force protection -3. Session fixation vulnerabilities -4. Insecure password storage (not bcrypt/argon2?) -5. Missing multi-factor authentication -6. Insecure "remember me" implementation -7. Password reset vulnerabilities - -Provide recommendations for each issue found. -``` - -### Authorization Flaws - -``` -Audit authorization controls: - -Check for: -1. Broken access control (IDOR) -2. Missing function-level access control -3. Privilege escalation paths -4. JWT vulnerabilities (algorithm confusion, weak secrets) -5. OAuth misconfigurations -6. CORS misconfigurations - -Test each endpoint for unauthorized access. -``` - -### Data Exposure - -``` -Check for sensitive data exposure: - -1. Are secrets hardcoded anywhere? -2. Is sensitive data logged? -3. Is PII properly encrypted at rest? -4. Is data encrypted in transit (TLS)? -5. Are error messages leaking information? -6. Is sensitive data in URLs (logged by proxies)? -7. Are backups encrypted? - -List all findings with severity ratings. -``` - -## Examples - -### Critical Vulnerability Fix - -``` -We have a critical remote code execution vulnerability: - -File: src/api/upload.py -Issue: Arbitrary file upload allows code execution - -Current code: -def upload_file(file): - filename = file.filename - file.save(os.path.join(UPLOAD_DIR, filename)) - return {"message": "Upload successful"} - -Fix this vulnerability: -1. Validate file extension against whitelist -2. Sanitize filename (remove path traversal) -3. Generate random filename -4. Scan file content for malicious patterns -5. Store outside web root -6. Add proper error handling -``` - -### Comprehensive Security Audit - -``` -Perform a comprehensive security audit of our authentication system: - -Files to review: -- src/auth/login.py -- src/auth/session.py -- src/auth/password.py -- src/middleware/auth.py - -Check for: -1. OWASP Authentication Cheat Sheet compliance -2. Password storage best practices -3. Session management security -4. Brute force protection -5. Account lockout mechanisms -6. Secure cookie settings -7. CSRF protection - -Provide a report with findings and fixes. -``` - -### Automated Remediation Pipeline +Create an end-to-end automated pipeline: ``` Create an automated vulnerability remediation pipeline: @@ -453,8 +255,22 @@ Create an automated vulnerability remediation pipeline: 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 -- [Security](/openhands/usage/admin/security) - Comprehensive security overview +- [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 From 47151897c1fe9c369b509d1f073f614c9d02370c Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 4 Feb 2026 17:19:16 +0000 Subject: [PATCH 04/19] Update Tutorial Library page - Rename from 'TODO-Tutorial Library' to 'Tutorial Library' - Remove 'Getting Started with Tutorials' section - Add Note linking to Use Cases section for in-depth guidance - Add Code Review cross-references: - Link to Code Review Use Case page - Link to PR Review SDK Guide (sdk/guides/github-workflows/pr-review) - Add Bug Fixing cross-reference to Incident Triage Use Case Co-authored-by: openhands --- openhands/usage/get-started/tutorials.mdx | 47 +++++++---------------- 1 file changed, 13 insertions(+), 34 deletions(-) diff --git a/openhands/usage/get-started/tutorials.mdx b/openhands/usage/get-started/tutorials.mdx index 8ef4d2d9..8e14fd52 100644 --- a/openhands/usage/get-started/tutorials.mdx +++ b/openhands/usage/get-started/tutorials.mdx @@ -1,5 +1,5 @@ --- -title: TODO-Tutorial Library +title: Tutorial Library description: Centralized hub for OpenHands tutorials and examples --- @@ -16,6 +16,10 @@ Welcome to the OpenHands tutorial library. These tutorials show you how to use O | [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: @@ -214,6 +218,10 @@ Include a README with usage instructions. ### 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 @@ -268,6 +276,10 @@ For each issue: ### 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 @@ -404,39 +416,6 @@ Include documentation and tests. --- -## Getting Started with Tutorials - -### Step 1: Choose the Right Tutorial - -Match your task to a tutorial: -- What type of work are you doing? -- What's the complexity level? -- Do you have similar patterns in your codebase? - -### Step 2: Prepare Your Repository - -Before starting: -1. Ensure your code builds and tests pass -2. Update AGENTS.md with relevant patterns -3. Commit any pending changes -4. Have clear success criteria - -### Step 3: Customize the Prompt - -Adapt tutorial prompts to your needs: -- Replace file paths with your actual paths -- Update technology references (frameworks, libraries) -- Add project-specific constraints -- Include examples from your codebase - -### Step 4: Iterate if Needed - -If the first attempt isn't perfect: -1. Review what OpenHands produced -2. Identify gaps or misunderstandings -3. Provide clarifying instructions -4. Build on the previous work - ## Contributing Tutorials Have a great use case? Share it with the community! From 2e5e0126a6808ec2ae28e5f07d2fc1d8832748af Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 4 Feb 2026 17:22:01 +0000 Subject: [PATCH 05/19] Redesign Quick Start page with cards Replace tabs-based layout with a card-based design: - OpenHands Cloud (recommended) - links to https://app.all-hands.dev - Local GUI - links to /openhands/usage/run-openhands/local-setup - Terminal / CLI - links to /openhands/usage/cli/installation Each card includes relevant icons and bullet points highlighting key features. Co-authored-by: openhands --- overview/quickstart.mdx | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/overview/quickstart.mdx b/overview/quickstart.mdx index 54bfb9fd..40c06cf8 100644 --- a/overview/quickstart.mdx +++ b/overview/quickstart.mdx @@ -1,19 +1,32 @@ --- title: Quick Start -description: Running OpenHands Cloud or running on your own. +description: Choose how you want to run OpenHands --- - - - The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $10 in free credits for new users. +Get started with OpenHands in minutes. Choose the option that works best for you. - To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev). + + + **Recommended** - 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. + The fastest way to get started. No setup required—just sign in and start coding. - For more information see [running OpenHands on your own.](/openhands/usage/run-openhands/local-setup) - - + - $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 + + From 72bf01875a4c420feb2ed3aca289ca0f761eccbb Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 12:00:39 -0700 Subject: [PATCH 06/19] minor deletions, overview rework --- .../usage/use-cases/cobol-modernization.mdx | 23 ++++--------------- 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 8f28ccf4..2527fbe7 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -13,20 +13,20 @@ This guide is based on our blog post [Refactoring COBOL to Java with AI Agents]( [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 unique syntax making it difficult for human teams alone. - -AI is now achieving what armies of developers couldn't: automated code analysis, transformation, and verification at scale. +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 -Simply converting COBOL syntax to Java isn't enough—the converted code needs to preserve business logic, follow modern language conventions, and be maintainable by modern development teams. +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. -COBOL modernization with OpenHands focuses on three key areas: +OpenHands is a powerful agent that can assist 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. + ## Iterative Refinement Approach One effective method is an iterative refinement pattern using multiple agents in a feedback loop. The idea is simple: one agent does the work, another agent checks it, and if it's not good enough, the first agent tries again with the feedback. @@ -189,16 +189,6 @@ OpenHands can assist with translating COBOL to modern languages: -### Refactoring Approaches - -Different approaches for different needs: - -| Approach | Description | Best For | -|----------|-------------|----------| -| Lift and shift | Direct translation preserving structure | Quick migration, minimal risk | -| Restructure | Translate and improve code organization | Medium-term maintainability | -| Re-architect | Redesign using modern patterns | Long-term strategic value | - ## Scaling Up with the Large Codebase SDK The iterative refinement example works well for small to medium codebases. But enterprise COBOL systems can span millions of lines across thousands of programs, with complex interdependencies. @@ -260,9 +250,6 @@ Validate that modernized code produces correct output: 4. **Translate incrementally**: Convert one section at a time 5. **Validate continuously**: Run tests after each translation step - -COBOL modernization is a complex undertaking. OpenHands works best as an assistant to experienced developers rather than a fully autonomous solution for large-scale migrations. - ## Related Resources From 879790ec95a9ec8fc7d29f371f722bc317cc60d6 Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 12:05:20 -0700 Subject: [PATCH 07/19] re-organize sections to match flow --- .../usage/use-cases/cobol-modernization.mdx | 184 ++++++++---------- 1 file changed, 78 insertions(+), 106 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 2527fbe7..2933c905 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -19,7 +19,7 @@ The challenge is acute: [47% of organizations](https://softwaremodernizationserv 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 can assist in modernizing COBOL code along every step of the process: +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# @@ -27,84 +27,7 @@ OpenHands is a powerful agent that can assist in modernizing COBOL code along ev In this document, we will explore the different ways OpenHands contributes to COBOL modernization, with example prompts and techniques. -## Iterative Refinement Approach - -One effective method is an iterative refinement pattern using multiple agents in a feedback loop. The idea is simple: one agent does the work, another agent checks it, and if it's not good enough, the first agent tries again with the feedback. - -Here's what that looks like in code using the [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk): - -```python -while current_score < QUALITY_THRESHOLD and iteration < MAX_ITERATIONS: - # Refactoring agent converts COBOL to Java - refactoring_conversation.send_message(refactoring_prompt) - refactoring_conversation.run() - - # Critique 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) -``` - -The result is more than just code that runs—it's code that faithfully reproduces the original and meets your standards on quality and maintainability. - -### How It Works - -The **refactoring agent** receives instructions about conversion requirements: preserve business logic, use Java naming conventions, implement error handling, and add documentation. - -The **critique agent** evaluates each converted file on correctness, code quality, completeness, and best practices—producing a structured report with specific issues to address. - -If the result isn't up to your specified standard, the refactoring agent runs again with the critique feedback, making targeted improvements. - -### Example Transformation - -Here's a COBOL customer management program: - -```cobol -1000-MAIN-PROCESS. - DISPLAY "CUSTOMER MANAGEMENT SYSTEM" - EVALUATE TRUE - WHEN OP-ADD - PERFORM 2000-ADD-CUSTOMER - WHEN OP-UPDATE - PERFORM 3000-UPDATE-CUSTOMER - WHEN OP-DELETE - PERFORM 4000-DELETE-CUSTOMER - END-EVALUATE. -``` - -The agent converts this to idiomatic Java: - -```java -public class CustomerManagement { - public void mainProcess() { - System.out.println("CUSTOMER MANAGEMENT SYSTEM"); - switch (operation) { - case ADD -> addCustomer(); - case UPDATE -> updateCustomer(); - case DELETE -> deleteCustomer(); - default -> System.out.println("INVALID OPERATION"); - } - } -} -``` - -## 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. - -## Code Analysis - -### COBOL Code Understanding +## Understanding OpenHands can help you understand COBOL programs by: @@ -144,9 +67,7 @@ Document each rule with: 3. Any edge cases or special conditions ``` -## Modernization Strategies - -### Translation to Modern Languages +## Translation OpenHands can assist with translating COBOL to modern languages: @@ -189,13 +110,78 @@ OpenHands can assist with translating COBOL to modern languages: -## Scaling Up with the Large Codebase SDK +### Example Transformation + +Here's a COBOL customer management program: + +```cobol +1000-MAIN-PROCESS. + DISPLAY "CUSTOMER MANAGEMENT SYSTEM" + EVALUATE TRUE + WHEN OP-ADD + PERFORM 2000-ADD-CUSTOMER + WHEN OP-UPDATE + PERFORM 3000-UPDATE-CUSTOMER + WHEN OP-DELETE + PERFORM 4000-DELETE-CUSTOMER + END-EVALUATE. +``` + +The agent converts this to idiomatic Java: + +```java +public class CustomerManagement { + public void mainProcess() { + System.out.println("CUSTOMER MANAGEMENT SYSTEM"); + switch (operation) { + case ADD -> addCustomer(); + case UPDATE -> updateCustomer(); + case DELETE -> deleteCustomer(); + default -> System.out.println("INVALID OPERATION"); + } + } +} +``` + +### Iterative Refinement + +One effective method is an iterative refinement pattern using multiple agents in a feedback loop. The idea is simple: one agent does the work, another agent checks it, and if it's not good enough, the first agent tries again with the feedback. + +Here's what that looks like in code using the [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk): + +```python +while current_score < QUALITY_THRESHOLD and iteration < MAX_ITERATIONS: + # Refactoring agent converts COBOL to Java + refactoring_conversation.send_message(refactoring_prompt) + refactoring_conversation.run() + + # Critique 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) +``` + +The result is more than just code that runs—it's code that faithfully reproduces the original and meets your standards on quality and maintainability. + +#### How It Works + +The **refactoring agent** receives instructions about conversion requirements: preserve business logic, use Java naming conventions, implement error handling, and add documentation. + +The **critique agent** evaluates each converted file on correctness, code quality, completeness, and best practices—producing a structured report with specific issues to address. + +If the result isn't up to your specified standard, the refactoring agent runs again with the critique feedback, making targeted improvements. + +### Scaling Up with the Large Codebase SDK The iterative refinement example works well for small to medium codebases. But enterprise COBOL systems can span millions of lines across thousands of programs, with complex interdependencies. For these large-scale modernization projects, the OpenHands Large Codebase SDK extends the iterative refinement pattern with specialized COBOL refactoring workflows that understand common mainframe patterns—CICS transactions, JCL jobs, VSAM file handling—and convert them to appropriate Java equivalents. -## Testing and Validation + +## Validation + ### Behavior Preservation @@ -224,31 +210,17 @@ Validate that modernized code produces correct output: - **Decimal precision**: Verify monetary calculations are exact - **Date handling**: Confirm date conversions are correct -## Best Practices - -### Effective Prompts for COBOL Work - -- **Provide context**: Include relevant copybooks and called programs -- **Specify standards**: Define your target coding standards -- **Request documentation**: Ask for mapping documents alongside translations -- **Iterate incrementally**: Translate and validate in small chunks - -### Common Pitfalls to Avoid +## Try It Yourself - -- **Don't translate everything at once**: Large batch translations are error-prone -- **Don't ignore packed decimal handling**: Ensure proper numeric conversions -- **Don't skip testing**: Every translation needs validation -- **Don't lose business knowledge**: Document rules before translating - +The full iterative refinement example is available in the OpenHands SDK: -### Recommended Workflow +```bash +export LLM_API_KEY="your-api-key" +cd software-agent-sdk +uv run python examples/01_standalone_sdk/31_iterative_refinement.py +``` -1. **Document first**: Have OpenHands analyze and document the COBOL program -2. **Extract rules**: Identify and document all business rules -3. **Create tests**: Build test cases from the documentation -4. **Translate incrementally**: Convert one section at a time -5. **Validate continuously**: Run tests after each translation step +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 From 72b817df9b38c9f00a8e8cf4ccfef38b342ced3a Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 13:07:14 -0700 Subject: [PATCH 08/19] understanding section rewrite --- .../usage/use-cases/cobol-modernization.mdx | 52 +++++++------------ 1 file changed, 19 insertions(+), 33 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 2933c905..c723764c 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -25,47 +25,33 @@ OpenHands is a powerful agent that assists in modernizing COBOL code along every 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. +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 -OpenHands can help you understand COBOL programs by: +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. -- **Explaining program structure**: Identifying divisions, sections, and paragraphs -- **Documenting data definitions**: Parsing WORKING-STORAGE and FILE SECTION entries -- **Tracing program flow**: Following PERFORM statements and GO TO branches -- **Identifying business rules**: Extracting logic from PROCEDURE DIVISION code +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: -**Example prompt:** ``` -Analyze the COBOL program in src/CUSTMGMT.cbl and explain: -1. What business function does this program perform? -2. What are the main data structures used? -3. What external files or databases does it interact with? -4. Create a flowchart of the main processing logic. +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" + ], + }, + ... +} ``` -### Business Logic Extraction - -Extract and document business rules embedded in COBOL: - -- **Calculation rules**: Interest calculations, pricing formulas, fee structures -- **Validation rules**: Data validation, business constraint checking -- **Decision logic**: Complex IF/EVALUATE structures and their conditions -- **Processing sequences**: Order of operations and dependencies - -**Example prompt:** -``` -Extract all business rules from LOANPROC.cbl related to: -- Interest rate calculations -- Payment scheduling -- Late fee assessment - -Document each rule with: -1. The COBOL code implementing it -2. A plain English description -3. Any edge cases or special conditions -``` +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 From 7e88ac2042e46fd35e921ed755ddce9b23d18610 Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 15:10:23 -0700 Subject: [PATCH 09/19] scaling up moved, rewritten --- .../usage/use-cases/cobol-modernization.mdx | 99 ++++++++++++------- 1 file changed, 63 insertions(+), 36 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index c723764c..26673c36 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -129,42 +129,6 @@ public class CustomerManagement { } ``` -### Iterative Refinement - -One effective method is an iterative refinement pattern using multiple agents in a feedback loop. The idea is simple: one agent does the work, another agent checks it, and if it's not good enough, the first agent tries again with the feedback. - -Here's what that looks like in code using the [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk): - -```python -while current_score < QUALITY_THRESHOLD and iteration < MAX_ITERATIONS: - # Refactoring agent converts COBOL to Java - refactoring_conversation.send_message(refactoring_prompt) - refactoring_conversation.run() - - # Critique 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) -``` - -The result is more than just code that runs—it's code that faithfully reproduces the original and meets your standards on quality and maintainability. - -#### How It Works - -The **refactoring agent** receives instructions about conversion requirements: preserve business logic, use Java naming conventions, implement error handling, and add documentation. - -The **critique agent** evaluates each converted file on correctness, code quality, completeness, and best practices—producing a structured report with specific issues to address. - -If the result isn't up to your specified standard, the refactoring agent runs again with the critique feedback, making targeted improvements. - -### Scaling Up with the Large Codebase SDK - -The iterative refinement example works well for small to medium codebases. But enterprise COBOL systems can span millions of lines across thousands of programs, with complex interdependencies. - -For these large-scale modernization projects, the OpenHands Large Codebase SDK extends the iterative refinement pattern with specialized COBOL refactoring workflows that understand common mainframe patterns—CICS transactions, JCL jobs, VSAM file handling—and convert them to appropriate Java equivalents. - ## Validation @@ -196,6 +160,69 @@ Validate that modernized code produces correct output: - **Decimal precision**: Verify monetary calculations are exact - **Date handling**: Confirm date conversions are correct +## 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: From ae53972c823f246c7f170432b9bb13a917184b9c Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 15:25:57 -0700 Subject: [PATCH 10/19] validation restructure --- .../usage/use-cases/cobol-modernization.mdx | 28 ++----------------- 1 file changed, 2 insertions(+), 26 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 26673c36..8d857aa1 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -132,33 +132,9 @@ public class CustomerManagement { ## 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. -### Behavior Preservation - -Ensure modernized code produces identical results: - -- **Golden file testing**: Capture COBOL outputs as test expectations -- **Comparison testing**: Run both versions with identical inputs -- **Edge case coverage**: Test boundary conditions and error paths -- **Performance validation**: Verify acceptable performance characteristics - -**Example prompt:** -``` -Create a test suite to validate the Java translation of PAYROLL.cbl: -1. Extract 100 representative test cases from production data -2. Run both COBOL and Java versions with these inputs -3. Compare outputs field by field -4. Generate a report of any discrepancies -``` - -### Output Validation - -Validate that modernized code produces correct output: - -- **Field-level comparison**: Match every output field -- **Format verification**: Ensure reports and files match expected formats -- **Decimal precision**: Verify monetary calculations are exact -- **Date handling**: Confirm date conversions are correct +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 From 8dc892766ada2bf30e1e869ba88226f40b8a0a5f Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 15:40:11 -0700 Subject: [PATCH 11/19] tranlsation rewrite --- .../usage/use-cases/cobol-modernization.mdx | 89 ++++--------------- 1 file changed, 19 insertions(+), 70 deletions(-) diff --git a/openhands/usage/use-cases/cobol-modernization.mdx b/openhands/usage/use-cases/cobol-modernization.mdx index 8d857aa1..4044465d 100644 --- a/openhands/usage/use-cases/cobol-modernization.mdx +++ b/openhands/usage/use-cases/cobol-modernization.mdx @@ -55,80 +55,29 @@ OpenHands uses tools like `grep`, `sed`, and `awk` to navigate files and pull in ## Translation -OpenHands can assist with translating COBOL to modern languages: +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. - - - **Best for**: Enterprise applications, existing Java ecosystems - - ``` - Translate CUSTMGMT.cbl to Java, following these guidelines: - - Use Java 17 features where appropriate - - Create separate classes for data structures and business logic - - Use BigDecimal for all monetary calculations - - Add JavaDoc comments explaining the original COBOL structure - - Create a mapping document showing COBOL to Java correspondence - ``` - - - **Best for**: Data processing, analytics, rapid prototyping - - ``` - Translate RPTGEN.cbl to Python, following these guidelines: - - Use Python 3.11+ features - - Use dataclasses for record structures - - Use Decimal for monetary calculations - - Preserve the original program's logic flow - - Add type hints throughout - ``` - - - **Best for**: Windows environments, .NET ecosystems - - ``` - Translate INVPROC.cbl to C#, following these guidelines: - - Target .NET 8 - - Use records for data structures - - Use decimal for monetary values - - Follow Microsoft naming conventions - - Add XML documentation comments - ``` - - - -### Example Transformation - -Here's a COBOL customer management program: - -```cobol -1000-MAIN-PROCESS. - DISPLAY "CUSTOMER MANAGEMENT SYSTEM" - EVALUATE TRUE - WHEN OP-ADD - PERFORM 2000-ADD-CUSTOMER - WHEN OP-UPDATE - PERFORM 3000-UPDATE-CUSTOMER - WHEN OP-DELETE - PERFORM 4000-DELETE-CUSTOMER - END-EVALUATE. -``` +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. -The agent converts this to idiomatic Java: - -```java -public class CustomerManagement { - public void mainProcess() { - System.out.println("CUSTOMER MANAGEMENT SYSTEM"); - switch (operation) { - case ADD -> addCustomer(); - case UPDATE -> updateCustomer(); - case DELETE -> deleteCustomer(); - default -> System.out.println("INVALID OPERATION"); - } - } -} +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 From c5d3966dda4b0550411f313f34a1e1f426261ce6 Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Mon, 9 Feb 2026 13:30:38 -0700 Subject: [PATCH 12/19] spark migration rewrite, first pass --- .../usage/use-cases/spark-migrations.mdx | 423 ++++-------------- 1 file changed, 90 insertions(+), 333 deletions(-) diff --git a/openhands/usage/use-cases/spark-migrations.mdx b/openhands/usage/use-cases/spark-migrations.mdx index b4c213be..b14ecc7e 100644 --- a/openhands/usage/use-cases/spark-migrations.mdx +++ b/openhands/usage/use-cases/spark-migrations.mdx @@ -1,391 +1,148 @@ --- -title: TODO-Spark Migrations +title: 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. +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 analyze, migrate, and validate Spark applications. ## Overview -OpenHands assists with Spark migrations in several ways: +Spark version upgrades are deceptively difficult. The [Spark 3.0 migration guide](https://spark.apache.org/docs/latest/migration-guide.html) alone documents hundreds of behavioral changes, deprecated APIs, and removed features, and many of these changes are _semantic_. That means the same code compiles and runs but produces different results across different Spark versions: for example, a date parsing expression that worked correctly in Spark 2.4 may silently return different values in Spark 3.x due to the switch from the Julian calendar to the Gregorian calendar. -- **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 +Version upgrades are also made difficult due to the scale of typical enterprise Spark codebases. When you have dozens of jobs across ETL, reporting, and ML pipelines, each with its own combination of DataFrame operations, UDFs, and configuration, manual migration stops scaling well and becomes prone to subtle regressions. -## Migration Scenarios +Spark migration requires careful analysis, targeted code changes, and thorough validation to ensure that migrated pipelines produce identical results. The migration needs to be driven by an experienced data engineering team, but even that isn't sufficient to ensure the job is done quickly or without regressions. This is where OpenHands comes in. -### Spark Version Upgrades +Such migrations need to be driven by experienced data engineering teams that understand how your Spark pipelines interact, but even that isn't sufficient to ensure the job is done quickly or without regression. This is where OpenHands comes in. OpenHands assists in migrating Spark applications along every step of the process: -Upgrading Spark versions often requires code changes due to API deprecations and behavioral differences. +1. **Understanding**: Analyze the existing codebase to identify what needs to change and why +2. **Migration**: Apply targeted code transformations that address API changes and behavioral differences +3. **Validation**: Verify that migrated pipelines produce identical results to the originals -**Spark 2.x to 3.x Migration:** +In this document, we will explore how OpenHands contributes to Spark migrations, with example prompts and techniques to use in your own efforts. While the examples focus on Spark 2.x to 3.x upgrades, the same principles apply to cloud platform migrations, framework conversions (MapReduce, Hive, Pig to Spark), and upgrades between Spark 3.x minor versions. -``` -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. -``` +## Understanding -**Common migration areas:** +Before changin any code, it helps to build a clear picture of what is affected and where the risk is concentrated. Spark migrations touch a large surface area, between API deprecations, behavioral changes, configuration defaults, and dependency versions, and the interactions between them are hard to reason about manually. -| 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 | +Apache releases detailed lists of changes between each major and minor version of Spark. OpenHands can utilize this list of changes while scanning your codebase to produce a structured inventory of everything that needs attention. This inventory becomes the foundation for the migration itself, helping you prioritize work and track progress. -### Migration from Other Big Data Frameworks - -**MapReduce to Spark:** +If your Spark project is in `/src` and you're migrating from 2.4 to 3.0, the following prompt will generate this inventory: ``` -Convert our MapReduce jobs to Spark: +Analyze the Spark application in `/src` for a migration from Spark 2.4 to Spark 3.0. -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 -``` +Examine the migration guidelines at https://spark.apache.org/docs/latest/migration-guide.html. -**Hive to Spark SQL:** +Then, for each source file, identify -``` -Migrate our Hive ETL pipeline to Spark: +1. Deprecated or removed API usages (e.g., `registerTempTable`, `unionAll`, `SQLContext`) +2. Behavioral changes that could affect output (e.g., date/time parsing, CSV parsing, CAST semantics) +3. Configuration properties that have changed defaults or been renamed +4. Dependencies that need version updates -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: +Save the results in `migration_inventory.json` in the following format: -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 +{ + ..., + "src/main/scala/etl/TransformJob.scala": { + "deprecated_apis": [ + {"line": 42, "current": "df.registerTempTable(\"temp\")", "replacement": "df.createOrReplaceTempView(\"temp\")"} + ], + "behavioral_changes": [ + {"line": 78, "description": "to_date() uses proleptic Gregorian calendar in Spark 3.x; verify date handling with test data"} + ], + "config_changes": [], + "risk": "medium" + }, + ... +} ``` -### 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:** +Tools like `grep` and `find` (both used by OpenHands) are helpful for identifying where APIs are used, but the real value comes from OpenHands' ability to understand the _context_ around each usage. A simple `registerTempTable` call is migrated via a rename, but a date parsing expression requires understanding how the surrounding pipeline uses the result. This contextual analysis helps developers distinguish between mechanical fixes and changes that need careful testing. -``` -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 -``` +## Migration -## Code Transformation +With a clear inventory of what needs to change, the next step is applying the transformations. Spark migrations involve a mix of straightforward API renames and subtler behavioral adjustments, and it's important to handle them differently. -### API Updates +To handle simple renames, we prompt OpenHands to use tools like `grep` and `ast-grep` instead of manually manipulating source code. This saves tokens and also simplifies future migrations, as agents can reliably re-run the tools via a script. -OpenHands can automatically update deprecated APIs: +The main risk in migration is that many Spark 3.x behavioral changes are _silent_. The migrated code will compile and run without errors, but may produce different results. Date and timestamp handling is the most common source of these silent failures: Spark 3.x switched to the Gregorian calendar by default, which changes how dates before 1582-10-15 are interpreted. CSV and JSON parsing also became stricter in Spark 3.x, rejecting malformed inputs that Spark 2.x would silently accept. -``` -Update all deprecated Spark APIs in our codebase: +An example prompt is below: -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 ``` +Migrate the Spark application in `/src` from Spark 2.4 to Spark 3.0. -**Common API updates:** +Use `migration_inventory.json` to guide the changes. -```scala -// Before (Spark 2.x) -val df = spark.read.format("json").load(path) -df.registerTempTable("temp") +For all low-risk changes (minor syntax changes, updated APIs, etc.), use tools like `grep` or `ast-grep`. Make sure you write the invocations to a `migration.sh` script for future use. -// After (Spark 3.x) -val df = spark.read.format("json").load(path) -df.createOrReplaceTempView("temp") +Requirements: +1. Replace all deprecated APIs with their Spark 3.0 equivalents +2. For behavioral changes (especially date handling and CSV parsing), add explicit configuration to preserve Spark 2.4 behavior where needed (e.g., spark.sql.legacy.timeParserPolicy=LEGACY) +3. Update build.sbt / pom.xml dependencies to Spark 3.0 compatible versions +4. Replace RDD-based operations with DataFrame/Dataset equivalents where practical +5. Replace UDFs with built-in Spark SQL functions where a direct equivalent exists +6. Update import statements for any relocated classes +7. Preserve all existing business logic and output schemas ``` -### 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 -``` +Note the inclusion of the _known problems_ in requirement 2. We plan to catch the silent failures associated with these systems in the validation step, but including them explicitly while migrating helps avoid them altogether. -**Key optimization patterns:** +## Validation -| 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 | +Spark migrations are particularly prone to silent regressions: jobs appear to run successfully but produce subtly different output. Jobs dealing with dates, CSVs, or using CAST semantics are all vulnerable, especially when migrating between major versions of Spark. -### Best Practices Application +The most reliable way to ensure silent regressions do not exist is by _data-level comparison_, where both the new and old pipelines are run on the same input data and their outputs directly compared. This catches subtle errors that unit tests might miss, especially in complex pipelines where a behavioral change in one stage propagates through downstream transformations. -Apply modern Spark best practices: +An example prompt for data-level comparison: ``` -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 +Validate the migrated Spark application in `/src` against the original. -Create comprehensive tests for migrated jobs: +1. For each job, run both the Spark 2.4 and 3.0 versions on the test data in `/test_data` +2. Compare outputs: + - Row counts must match exactly + - Perform column-level comparison using checksums for numeric columns and exact match for string/date columns + - Flag any NULL handling differences +3. For any discrepancies, trace them back to specific migration changes using the MIGRATION comments +4. Generate a performance comparison: job duration, shuffle bytes, and peak executor memory -``` -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 -``` +Save the results in `validation_report.json` in the following format: -**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) - } +{ + "jobs": [ + { + "name": "daily_etl", + "data_match": true, + "row_count": {"v2": 1000000, "v3": 1000000}, + "column_diffs": [], + "performance": { + "duration_seconds": {"v2": 340, "v3": 285}, + "shuffle_bytes": {"v2": "2.1GB", "v3": "1.8GB"} + } + }, + ... + ] } ``` -### Performance Benchmarking +Note this prompt relies on existing data in `/test_data`. This can be generated by standard fuzzing tools, but in a pinch OpenHands can also help construct synthetic data that stresses the potential corner cases in the relevant systems. -Compare performance between versions: +Every migration is unique, and developer experience is crucial to ensure the testing strategy covers your organization's requirements. Pay particular attention to jobs that involve date arithmetic, decimal precision in financial calculations, or custom UDFs that may depend on Spark internals. A solid validation suite not only ensures the migrated code works as expected, but also builds the organizational confidence needed to deploy the new version to production. -``` -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:** +## Beyond Version Upgrades -- Job duration (wall clock time) -- Shuffle read/write bytes -- Peak executor memory -- Task distribution (min/max/median) -- Garbage collection time +While this document focuses on Spark version upgrades, the same Understanding → Migration → Validation workflow applies to other Spark migration scenarios: -### Data Validation +- **Cloud platform migrations** (e.g., EMR to Databricks, on-premises to Dataproc): The "understanding" step inventories platform-specific code (S3 paths, IAM roles, EMR bootstrap scripts), the migration step converts them to the target platform's equivalents, and validation confirms that jobs produce identical output in the new environment. +- **Framework migrations** (MapReduce, Hive, or Pig to Spark): The "understanding" step maps the existing framework's operations to Spark equivalents, the migration step performs the conversion, and validation compares outputs between the old and new frameworks. -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 -``` +In each case, the key principle is the same: build a structured inventory of what needs to change, apply targeted transformations, and validate rigorously before deploying. ## Related Resources -- [Repository Setup](/openhands/usage/customization/repository) - Configure your Spark repository for OpenHands -- [Key Features](/openhands/usage/key-features) - OpenHands capabilities overview +- [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents +- [Spark 3.x Migration Guide](https://spark.apache.org/docs/latest/migration-guide.html) - Official Spark migration documentation - [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts From 4144c96e5c6006c011b3e1220e78c6fded8da444 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 16:23:11 +0000 Subject: [PATCH 13/19] Update code-review.mdx to match main branch Sync openhands/usage/use-cases/code-review.mdx with the updated version from main that includes the Software Agent SDK-based PR review workflow documentation. --- openhands/usage/use-cases/code-review.mdx | 557 ++++++++-------------- 1 file changed, 208 insertions(+), 349 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 1e9ca0a2..d6d76beb 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -1,408 +1,267 @@ --- -title: TODO-Code Review -description: Leveraging OpenHands for automated and assisted code review +title: Automated Code Review +description: Set up automated PR reviews using OpenHands and the Software Agent SDK --- -Code review is essential for maintaining code quality, sharing knowledge, and catching bugs before they reach production. OpenHands can assist with code reviews by analyzing changes, identifying potential issues, and suggesting improvements. +Automated code review helps maintain code quality, catch bugs early, and enforce coding standards consistently across your team. OpenHands provides a GitHub Actions workflow powered by the [Software Agent SDK](/sdk/index) that automatically reviews pull requests and posts inline comments directly on your PRs. ## Overview -OpenHands enhances your code review process by: +The OpenHands PR Review workflow is a GitHub Actions workflow that: -- **Automated analysis**: Detecting bugs, security issues, and code smells -- **Standards enforcement**: Checking adherence to coding guidelines -- **Improvement suggestions**: Recommending better patterns and practices -- **Documentation**: Generating summaries and explanations of changes +- **Triggers automatically** when PRs are opened or when you request a review +- **Analyzes code changes** in the context of your entire repository +- **Posts inline comments** directly on specific lines of code in the PR +- **Provides fast feedback** - typically within 2-3 minutes -## Automated Code Review +## How It Works -### Code Quality Analysis +The PR review workflow uses the OpenHands Software Agent SDK to analyze your code changes: -OpenHands can analyze code changes for quality issues: +1. **Trigger**: The workflow runs when: + - A new non-draft PR is opened + - A draft PR is marked as ready for review + - The `review-this` label is added to a PR + - `openhands-agent` is requested as a reviewer -``` -Review the changes in this pull request for code quality: - -1. Identify any code smells (long methods, deep nesting, etc.) -2. Check for proper error handling -3. Verify logging is appropriate and consistent -4. Look for potential memory leaks or resource handling issues -5. Assess test coverage of the changes -6. Rate overall code quality and explain your assessment -``` +2. **Analysis**: The agent receives the complete PR diff and uses two skills: + - [**`/codereview`**](https://github.com/OpenHands/extensions/tree/main/skills/codereview) or [**`/codereview-roasted`**](https://github.com/OpenHands/extensions/tree/main/skills/codereview-roasted): Analyzes code for quality, security, and best practices + - [**`/github-pr-review`**](https://github.com/OpenHands/extensions/tree/main/skills/github-pr-review): Posts structured inline comments via the GitHub API -**What OpenHands checks for:** +3. **Output**: Review comments are posted directly on the PR with: + - Priority labels (🔴 Critical, 🟠 Important, 🟡 Suggestion, 🟢 Nit) + - Specific line references + - Actionable suggestions with code examples -| Category | Issues Detected | -|----------|----------------| -| Complexity | Long methods, deep nesting, high cyclomatic complexity | -| Maintainability | Code duplication, unclear naming, missing documentation | -| Reliability | Null pointer risks, unhandled exceptions, race conditions | -| Performance | N+1 queries, unnecessary allocations, inefficient algorithms | +### Review Styles -### Style and Standards Enforcement +Choose between two review styles: -Ensure code follows your team's standards: +| Style | Description | Best For | +|-------|-------------|----------| +| **Standard** ([`/codereview`](https://github.com/OpenHands/extensions/tree/main/skills/codereview)) | Pragmatic, constructive feedback focusing on code quality, security, and best practices | Day-to-day code reviews | +| **Roasted** ([`/codereview-roasted`](https://github.com/OpenHands/extensions/tree/main/skills/codereview-roasted)) | Linus Torvalds-style brutally honest review emphasizing "good taste", data structures, and simplicity | Critical code paths, learning opportunities | -``` -Review this PR against our coding standards: +## Quick Start -Standards document: docs/CODING_STANDARDS.md - -Check for: -1. Naming convention compliance -2. File organization -3. Import ordering -4. Comment formatting -5. Consistent spacing and indentation -6. Required documentation presence -``` - -**Example findings:** - -```python -# Issue: Function name doesn't follow snake_case convention -def processUserData(data): # Should be: process_user_data - pass - -# Issue: Missing docstring for public function -def calculate_total(items): - # Add: """Calculate the total price of all items.""" - return sum(item.price for item in items) -``` + + + Create `.github/workflows/pr-review-by-openhands.yml` in your repository: -### Bug Detection - -Identify potential bugs before they ship: - -``` -Analyze the code changes for potential bugs: - -1. Logic errors and edge cases -2. Off-by-one errors -3. Null/undefined handling -4. Type mismatches -5. Concurrency issues -6. Resource cleanup problems - -Provide specific line numbers and explanations for each issue found. -``` - -**Common bug patterns detected:** - - - - ```python - # Bug: Inverted condition - if user.is_active: - raise PermissionError("User is inactive") # Wrong! - - # Bug: Missing boundary check - def get_item(index): - return items[index] # No bounds checking - ``` - - - ```python - # Bug: File not closed on exception - def read_config(): - f = open("config.json") - data = json.load(f) # If this fails, file stays open - f.close() - return data - - # Fixed: - def read_config(): - with open("config.json") as f: - return json.load(f) - ``` - - - ```python - # Bug: Race condition - if key not in cache: - cache[key] = expensive_computation() # Another thread may have added it - return cache[key] - - # Fixed: Use setdefault or proper locking + ```yaml + name: PR Review by OpenHands + + on: + pull_request_target: + types: [opened, ready_for_review, labeled, review_requested] + + permissions: + contents: read + pull-requests: write + issues: write + + jobs: + pr-review: + if: | + (github.event.action == 'opened' && github.event.pull_request.draft == false) || + github.event.action == 'ready_for_review' || + github.event.label.name == 'review-this' || + github.event.requested_reviewer.login == 'openhands-agent' + runs-on: ubuntu-latest + steps: + - name: Run PR Review + uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + with: + llm-model: anthropic/claude-sonnet-4-5-20250929 + review-style: standard + llm-api-key: ${{ secrets.LLM_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` - - - -## Review Assistance - -### Generating Review Comments - -Get detailed review comments for a PR: - -``` -Generate code review comments for this pull request: - -For each issue found, provide: -1. The file and line number -2. The severity (critical, major, minor, suggestion) -3. A clear explanation of the issue -4. A suggested fix with code example - -Format the output as GitHub review comments. -``` - -**Example output:** - -``` -### src/api/users.py, line 45 -**Severity**: Major - -**Issue**: SQL injection vulnerability - -The user input is interpolated directly into the SQL query without sanitization. - -**Current code:** -query = f"SELECT * FROM users WHERE id = {user_id}" - -**Suggested fix:** -query = "SELECT * FROM users WHERE id = %s" -cursor.execute(query, (user_id,)) -``` + -### Identifying Potential Issues + + Go to your repository's **Settings → Secrets and variables → Actions** and add: + - **`LLM_API_KEY`**: Your LLM API key (get one from [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms)) + -Proactively find issues that might cause problems: + + Create a `review-this` label in your repository: + 1. Go to **Issues → Labels** + 2. Click **New label** + 3. Name: `review-this` + 4. Description: `Trigger OpenHands PR review` + -``` -Review this PR and identify potential issues: + + Open a PR and either: + - Add the `review-this` label, OR + - Request `openhands-agent` as a reviewer + + -Categories to check: -1. Security vulnerabilities -2. Performance bottlenecks -3. Backwards compatibility breaks -4. Missing error handling -5. Test coverage gaps -6. Documentation needs +## Composite Action -Rank issues by risk and effort to fix. -``` +The workflow uses a reusable composite action from the Software Agent SDK that handles all the setup automatically: -### Suggesting Improvements +- Checking out the SDK at the specified version +- Setting up Python and dependencies +- Running the PR review agent +- Uploading logs as artifacts -Get suggestions for making code better: - -``` -Suggest improvements for the code in this PR: +### Action Inputs -Focus on: -1. Cleaner, more idiomatic code -2. Better abstractions -3. Improved readability -4. Performance optimizations -5. More comprehensive testing -6. Enhanced documentation - -For each suggestion, explain the benefit and show before/after code. -``` - -**Example suggestion:** - -```python -# Before: Nested conditionals -def process_order(order): - if order.is_valid: - if order.payment_confirmed: - if order.items_in_stock: - return ship_order(order) - return None - -# After: Early returns -def process_order(order): - if not order.is_valid: - return None - if not order.payment_confirmed: - return None - if not order.items_in_stock: - return None - return ship_order(order) -``` +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `llm-model` | LLM model to use | Yes | - | +| `llm-base-url` | LLM base URL (for custom endpoints) | No | `''` | +| `review-style` | Review style: `standard` or `roasted` | No | `roasted` | +| `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | +| `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | +| `llm-api-key` | LLM API key | Yes | - | +| `github-token` | GitHub token for API access | Yes | - | -## Integration + +Use `sdk-version` to pin to a specific version tag (e.g., `v1.0.0`) for production stability, or use `main` to always get the latest features. + -### GitHub Pull Request Integration +## Customization -OpenHands integrates with GitHub for automated PR reviews: +### Repository-Specific Review Guidelines -1. **Install the GitHub App**: See [GitHub Integration](/openhands/usage/cloud/github-installation) -2. **Configure auto-review**: Enable automatic review on PR creation -3. **Trigger manual reviews**: Comment `@openhands review` on any PR +Create custom review guidelines for your repository by adding a skill file at `.agents/skills/code-review.md`: -**Automatic review workflow:** +```markdown +--- +name: code-review +description: Custom code review guidelines for this repository +triggers: +- /codereview +--- -```yaml -# .github/workflows/openhands-review.yml -name: OpenHands Code Review -on: - pull_request: - types: [opened, synchronize] - -jobs: - review: - runs-on: ubuntu-latest - steps: - - uses: openhands/review-action@v1 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - review-type: comprehensive -``` +# Repository Code Review Guidelines -### GitLab Merge Request Integration +You are reviewing code for [Your Project Name]. Follow these guidelines: -For GitLab users: +## Review Decisions -1. **Install the GitLab integration**: See [GitLab Integration](/openhands/usage/cloud/gitlab-installation) -2. **Configure webhook triggers**: Enable review on MR creation -3. **Manual trigger**: Comment `/openhands review` on any MR +### When to APPROVE +- Configuration changes following existing patterns +- Documentation-only changes +- Test-only changes without production code changes +- Simple additions following established conventions -### CI/CD Pipeline Integration +### When to COMMENT +- Issues that need attention (bugs, security concerns) +- Suggestions for improvement +- Questions about design decisions -Add code review to your CI/CD pipeline: +## Core Principles - - - ```yaml - - name: OpenHands Review - uses: openhands/review-action@v1 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - fail-on: critical # Fail CI if critical issues found - ``` - - - ```yaml - code_review: - stage: review - script: - - openhands review --format=gitlab - allow_failure: false - ``` - - - ```bash - # Run OpenHands review and output results - openhands review \ - --base-branch main \ - --format json \ - --output review-results.json - - # Fail if critical issues found - if jq -e '.critical_count > 0' review-results.json; then - exit 1 - fi - ``` - - +1. **[Your Principle 1]**: Description +2. **[Your Principle 2]**: Description -## Best Practices +## What to Check -### Effective Review Prompts +- **[Category 1]**: What to look for +- **[Category 2]**: What to look for -Write prompts that get useful reviews: +## Repository Conventions +- Use [your linter] for style checking +- Follow [your style guide] +- Tests should be in [your test directory] ``` -Review this PR with focus on: -- Security: We handle user PII in this code -- Performance: This runs in a hot path (1000+ calls/sec) -- Backwards compatibility: This is a public API - -Context: -- This is a Python 3.11 project using FastAPI -- We follow PEP 8 and Google style docstrings -- Database is PostgreSQL with SQLAlchemy ORM - -Ignore: -- Formatting issues (handled by pre-commit) -- Import ordering (handled by isort) -``` - -### Combining Human and AI Review - -Get the best of both worlds: - -1. **First pass: OpenHands** - - Automated checks for common issues - - Consistency verification - - Initial quality assessment -2. **Second pass: Human reviewer** - - Architecture and design decisions - - Business logic correctness - - Knowledge transfer and mentoring + +The skill file must use `/codereview` as the trigger to override the default review behavior. See the [software-agent-sdk's own code-review skill](https://github.com/OpenHands/software-agent-sdk/blob/main/.agents/skills/code-review.md) for a complete example. + -3. **Final pass: Author response** - - Address all feedback - - Explain any disagreements - - Request re-review if needed +### Workflow Configuration -### Review Scope Guidelines +Customize the workflow by modifying the action inputs: -| Change Size | Recommended Approach | -|-------------|---------------------| -| Small (under 50 lines) | Full automated review | -| Medium (50-200 lines) | Automated + focused human review | -| Large (over 200 lines) | Split PR or section-by-section review | -| Refactoring | Focus on behavior preservation | -| New feature | Focus on design and test coverage | - -## Examples - -### Security-Focused Review - -``` -Perform a security review of this PR: - -1. Check for injection vulnerabilities (SQL, XSS, command injection) -2. Verify authentication and authorization checks -3. Look for sensitive data exposure -4. Check cryptographic implementations -5. Verify input validation -6. Review error messages for information leakage - -Rate each finding by CVSS severity and provide remediation steps. +```yaml +- name: Run PR Review + uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + with: + # Change the LLM model + llm-model: anthropic/claude-sonnet-4-5-20250929 + # Use a custom LLM endpoint + llm-base-url: https://your-llm-proxy.example.com + # Switch to "roasted" style for brutally honest reviews + review-style: roasted + # Pin to a specific SDK version for stability + sdk-version: main + # Secrets + llm-api-key: ${{ secrets.LLM_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` -### Performance Review +### Trigger Customization -``` -Review this PR for performance: +Modify when reviews are triggered by editing the workflow conditions: -Context: This code runs in our order processing pipeline -handling 10,000 orders/minute. +```yaml +# Only trigger on label (disable auto-review on PR open) +if: github.event.label.name == 'review-this' -Check for: -1. Database query efficiency (N+1, missing indexes) -2. Memory allocations in loops -3. Blocking operations that could be async -4. Caching opportunities -5. Algorithm complexity +# Only trigger when specific reviewer is requested +if: github.event.requested_reviewer.login == 'openhands-agent' -Estimate the performance impact of any issues found. +# Trigger on all PRs (including drafts) +if: | + github.event.action == 'opened' || + github.event.action == 'synchronize' ``` -### API Review - -``` -Review this API change: - -Check for: -1. RESTful design principles -2. Consistent naming and URL structure -3. Appropriate HTTP methods and status codes -4. Request/response validation -5. Error handling and error messages -6. API documentation completeness -7. Backwards compatibility with v1 clients -``` +## Security Considerations + +The workflow uses `pull_request_target` so the code review agent can work properly for PRs from forks. Only users with write access can trigger reviews via labels or reviewer requests. + + +**Potential Risk**: A malicious contributor could submit a PR from a fork containing code designed to exfiltrate your `LLM_API_KEY` when the review agent analyzes their code. + +To mitigate this, the PR review workflow passes API keys as [SDK secrets](/sdk/guides/secrets) rather than environment variables, which prevents the agent from directly accessing these credentials during code execution. + + +## Example Reviews + +See real automated reviews in action on the OpenHands Software Agent SDK repository: + +| PR | Description | Review Highlights | +|----|-------------|-------------------| +| [#1927](https://github.com/OpenHands/software-agent-sdk/pull/1927#pullrequestreview-3767493657) | Composite GitHub Action refactor | Comprehensive review with 🔴 Critical, 🟠 Important, and 🟡 Suggestion labels | +| [#1916](https://github.com/OpenHands/software-agent-sdk/pull/1916#pullrequestreview-3758297071) | Add example for reconstructing messages | Critical issues flagged with clear explanations | +| [#1904](https://github.com/OpenHands/software-agent-sdk/pull/1904#pullrequestreview-3751821740) | Update code-review skill guidelines | APPROVED review highlighting key strengths | +| [#1889](https://github.com/OpenHands/software-agent-sdk/pull/1889#pullrequestreview-3747576245) | Fix tmux race condition | Technical review of concurrency fix with dual-lock strategy analysis | + +## Troubleshooting + + + + - Ensure the `LLM_API_KEY` secret is set correctly + - Check that the label name matches exactly (`review-this`) + - Verify the workflow file is in `.github/workflows/` + - Check the Actions tab for workflow run errors + + + + - Ensure `GITHUB_TOKEN` has `pull-requests: write` permission + - Check the workflow logs for API errors + - Verify the PR is not from a fork with restricted permissions + + + + - Large PRs may take longer to analyze + - Consider splitting large PRs into smaller ones + - Check if the LLM API is experiencing delays + + ## Related Resources -- [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration -- [GitLab Integration](/openhands/usage/cloud/gitlab-installation) - Set up GitLab integration -- [Integrations Overview](/openhands/usage/settings/integrations-settings) - All available integrations -- [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts +- [PR Review Workflow Reference](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) - Full workflow example and agent script +- [Composite Action](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/actions/pr-review/action.yml) - Reusable GitHub Action for PR reviews +- [Software Agent SDK](/sdk/index) - Build your own AI-powered workflows +- [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration for OpenHands Cloud +- [Skills Documentation](/overview/skills) - Learn more about OpenHands skills From c5cca0d785132eafafe6a60d2ef40ef049abebdf Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 17:27:50 +0000 Subject: [PATCH 14/19] Remove redundant V0 Configuration and V0 REST API links from nav These links were duplicated in the Additional Documentation section when they already exist under V0 Reference in the same navigation. Co-authored-by: openhands --- docs.json | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs.json b/docs.json index bdef0751..5e602a94 100644 --- a/docs.json +++ b/docs.json @@ -249,16 +249,6 @@ "overview/faqs", "openhands/usage/troubleshooting/feedback" ] - }, - { - "group": "V0 Configuration Options", - "pages": [ - "openhands/usage/v0/advanced/V0_configuration-options" - ] - }, - { - "group": "V0 REST API", - "openapi": "openapi/V0_openapi.json" } ] } From 3ae394e96a846a114ce3a383ec49d840e78b9d6b Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 17:32:43 +0000 Subject: [PATCH 15/19] Create OpenHands Community section, move Developers and Community groups - Created new 'OpenHands Community' section below 'Additional Documentation' - Moved 'Developers' group from Additional Documentation to OpenHands Community - Moved 'Community' group from Additional Documentation to OpenHands Community Co-authored-by: openhands --- docs.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 5e602a94..169c3f04 100644 --- a/docs.json +++ b/docs.json @@ -231,7 +231,12 @@ ] } ] - }, + } + ] + }, + { + "group": "OpenHands Community", + "pages": [ { "group": "Developers", "pages": [ From 95bafafbeced4008f5a5583c3ad119feb23a876c Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 17:34:38 +0000 Subject: [PATCH 16/19] Apply review suggestions from neubig - Update SDLC integration intro text - Add Linear task management reference - Add codecov module reference - Add codecov re-run guidance - Add Continuous Integration section with links to integrations - Remove empty Note block at end of file - Add detailed guidance on when to use OpenHands with specific task types Co-authored-by: openhands --- .../essential-guidelines/sdlc-integration.mdx | 24 +++++++++++++------ .../when-to-use-openhands.mdx | 17 ++++++++++--- 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/openhands/usage/essential-guidelines/sdlc-integration.mdx b/openhands/usage/essential-guidelines/sdlc-integration.mdx index 92931852..ec4ff168 100644 --- a/openhands/usage/essential-guidelines/sdlc-integration.mdx +++ b/openhands/usage/essential-guidelines/sdlc-integration.mdx @@ -3,7 +3,7 @@ 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. +OpenHands can enhance every phase of your software development lifecycle (SDLC), from planning through deployment. This guide shows some example prompts that you can use when you integrate OpenHands into your development workflow. ## Integration with Development Workflows @@ -30,7 +30,7 @@ Provide: **Sprint planning support:** ``` -Review these user stories and create implementation tasks: +Review these user stories and create implementation tasks in our Linear task management software using the LINEAR_API_KEY environment variable: Story 1: As a user, I can reset my password via email Story 2: As an admin, I can view user activity logs @@ -74,11 +74,13 @@ Add comprehensive tests for the UserService module: Current coverage: 45% Target coverage: 85% -1. Analyze uncovered code paths +1. Analyze uncovered code paths using the codecov module 2. Write unit tests for edge cases 3. Add integration tests for API endpoints 4. Create test data factories 5. Document test scenarios + +Each time you add new tests, re-run codecov to check the increased coverage. Continue until you have sufficient coverage, and all tests pass (by either fixing the tests, or fixing the code if your tests uncover bugs). ``` ### Review Phase @@ -252,6 +254,18 @@ steps: openhands review --format azure ``` +### Continuous Integration + +It is possible to use OpenHands not only through our GUI and CLI, but also through integrations into GitHub, GitLab, and BitBucket. + +This allows you to create actions to: + +1. Do automatic code review when a PR is opened +2. Automatically update docs weekly when new functionality is added +3. Diagnose errors that have appeared in monitoring software such as DataDog and automatically send analyses and improvements + +See the relevant links for examples. + ## Team Workflows ### Solo Developer Workflows @@ -491,7 +505,3 @@ jobs: 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 index 69816d66..a360a20d 100644 --- a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx +++ b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx @@ -277,6 +277,17 @@ Can you verify the result? └── 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. - +OpenHands can be used for most development tasks -- the developers of OpenHands write most of their code with OpenHands! + +But it can be particularly useful for certain types of tasks. For instance: + +- **Clearly Specified Tasks:** Generally, if the task has a very clear success criterion, OpenHands will do better. It is especially useful if you can define it in a way that can be verified programmatically, like making sure that all of the tests pass or test coverage gets above a certain value using a particular program. But even when you don't have something like that, you can just provide a checklist of things that need to be done. +- **Highly Repetitive Tasks:** These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create "[skills](TODO)" that clearly describe your policies about how to perform these tasks, and improve the skills over time. +- **Helping Answer Questions:** OpenHands agents are generally pretty good at answering questions about code bases, so you can feel free to ask them when you don't understand how something works. They can explore the code base and understand it deeply before providing an answer. +- **Checking the Correctness of Library/Backend Code:** when agents work, they can run code, and they are particularly good at checking whether libraries or backend code works well. +- **Reading Logs and Understanding Errors:** Agents can read blogs from GitHub or monitoring software and understand what is going wrong with your service in a live production setting. They're actually quite good at filtering through large amounts of data, especially if pushed in the correct direction. + +There are also some tasks where agent struggle a little more. + +- **Quality Assurance of Frontend Apps:** Agents can spin up a website and check whether it works by clicking through the buttons. But they are a little bit less good at visual understanding of frontends at the moment and can sometimes make mistakes if they don't understand the workflow very well. +- **Implementing Code they Cannot Test Live:** If agents are not able to actually run and test the app, such as connecting to a live service that they do not have access to, often they will fail at performing tasks all the way to the end, unless they get some encouragement. From 8ac02413dd44bb3207ad7d7e123f493283108341 Mon Sep 17 00:00:00 2001 From: jpelletier1 <44589723+jpelletier1@users.noreply.github.com> Date: Thu, 19 Feb 2026 12:56:39 -0500 Subject: [PATCH 17/19] Misc updates - Updated Dependency Updates use case - Removed 'TODO-' on some pages - Updated Community section - Removed $10 references --- docs.json | 25 ++-- openhands/usage/cli/quick-start.mdx | 2 +- .../good-vs-bad-instructions.mdx | 2 +- .../essential-guidelines/sdlc-integration.mdx | 2 +- .../when-to-use-openhands.mdx | 2 +- .../usage/use-cases/dependency-upgrades.mdx | 109 +----------------- overview/introduction.mdx | 2 +- overview/quickstart.mdx | 18 +-- 8 files changed, 28 insertions(+), 134 deletions(-) diff --git a/docs.json b/docs.json index 169c3f04..044b31d8 100644 --- a/docs.json +++ b/docs.json @@ -231,12 +231,7 @@ ] } ] - } - ] - }, - { - "group": "OpenHands Community", - "pages": [ + }, { "group": "Developers", "pages": [ @@ -245,17 +240,17 @@ "openhands/usage/developers/websocket-connection", "openhands/usage/developers/evaluation-harness" ] - }, - { - "group": "Community", - "pages": [ - "overview/community", - "overview/contributing", - "overview/faqs", - "openhands/usage/troubleshooting/feedback" - ] } ] + }, + { + "group": "OpenHands Community", + "pages": [ + "overview/community", + "overview/contributing", + "overview/faqs", + "openhands/usage/troubleshooting/feedback" + ] } ] }, diff --git a/openhands/usage/cli/quick-start.mdx b/openhands/usage/cli/quick-start.mdx index c86211d9..be5bf014 100644 --- a/openhands/usage/cli/quick-start.mdx +++ b/openhands/usage/cli/quick-start.mdx @@ -33,7 +33,7 @@ The OpenHands CLI provides multiple ways to interact with the OpenHands AI agent ```bash openhands login ``` - This authenticates with OpenHands Cloud and fetches your settings. First-time users get **$10 in free credits**. + This authenticates with OpenHands Cloud and fetches your settings. The CLI will prompt you to configure your LLM provider and API key on first run. diff --git a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx index 0fe82d8a..2801866b 100644 --- a/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx +++ b/openhands/usage/essential-guidelines/good-vs-bad-instructions.mdx @@ -1,5 +1,5 @@ --- -title: TODO-Good vs. Bad Instructions +title: Good vs. Bad Instructions description: Learn how to write effective instructions for OpenHands --- diff --git a/openhands/usage/essential-guidelines/sdlc-integration.mdx b/openhands/usage/essential-guidelines/sdlc-integration.mdx index ec4ff168..1a33a84d 100644 --- a/openhands/usage/essential-guidelines/sdlc-integration.mdx +++ b/openhands/usage/essential-guidelines/sdlc-integration.mdx @@ -1,5 +1,5 @@ --- -title: TODO-OpenHands in Your SDLC +title: OpenHands in Your SDLC description: How OpenHands fits into your software development lifecycle --- diff --git a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx index a360a20d..efe7a938 100644 --- a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx +++ b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx @@ -1,5 +1,5 @@ --- -title: TODO-When to Use OpenHands +title: When to Use OpenHands description: Guidance on when OpenHands is the right tool for your task --- diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index d602b5ea..10795fc2 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -14,7 +14,7 @@ OpenHands helps with dependency management by: - **Implementing changes**: Updating code to handle breaking changes - **Validating results**: Running tests and verifying functionality -## Dependency Analysis +## Dependency Analysis Examples ### Identifying Outdated Dependencies @@ -70,7 +70,7 @@ Check compatibility for upgrading React from 16 to 18: | styled-components | v5 ✓ | v5 ✓ | v5 ✓ | None | | material-ui | v4 ✓ | v4 ✓ | v5 required | Major upgrade | -## Automated Upgrades +## Automated Upgrade Examples ### Version Updates @@ -172,7 +172,7 @@ Migrate our codebase from moment.js to date-fns: | `moment().add(1, 'days')` | `addDays(new Date(), 1)` | Function-based API | | `moment().startOf('month')` | `startOfMonth(new Date())` | Separate function | -## Testing and Validation +## Testing and Validation Examples ### Automated Test Execution @@ -219,108 +219,7 @@ Check for regressions after upgrading the ORM: 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 +## Additional Examples ### Security-Driven Upgrade diff --git a/overview/introduction.mdx b/overview/introduction.mdx index 8f57b201..9f510db4 100644 --- a/overview/introduction.mdx +++ b/overview/introduction.mdx @@ -29,7 +29,7 @@ The experience will be familiar to anyone who has used Devin or Jules. ## OpenHands Cloud This is a commercial deployment of OpenHands GUI, running on hosted infrastructure. -You can try it with a free $10 credit by [signing in with your GitHub account](https://app.all-hands.dev). +You can try it with a free by [signing in with your GitHub account](https://app.all-hands.dev). OpenHands Cloud comes with source-available features and integrations: - Deeper integrations with GitHub, GitLab, and Bitbucket diff --git a/overview/quickstart.mdx b/overview/quickstart.mdx index 40c06cf8..843e997f 100644 --- a/overview/quickstart.mdx +++ b/overview/quickstart.mdx @@ -11,22 +11,22 @@ Get started with OpenHands in minutes. Choose the option that works best for you The fastest way to get started. No setup required—just sign in and start coding. - - $10 in free credits for new users + - Free usage of MiniMax M2.5 for a limited time - 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 + + 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 + From b78f2bd290c03337db4f19c9c94e96932cde9b94 Mon Sep 17 00:00:00 2001 From: Graham Neubig Date: Thu, 19 Feb 2026 13:10:01 -0500 Subject: [PATCH 18/19] Update openhands/usage/essential-guidelines/when-to-use-openhands.mdx Co-authored-by: OpenHands Bot --- openhands/usage/essential-guidelines/when-to-use-openhands.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx index efe7a938..23016039 100644 --- a/openhands/usage/essential-guidelines/when-to-use-openhands.mdx +++ b/openhands/usage/essential-guidelines/when-to-use-openhands.mdx @@ -282,7 +282,7 @@ OpenHands can be used for most development tasks -- the developers of OpenHands But it can be particularly useful for certain types of tasks. For instance: - **Clearly Specified Tasks:** Generally, if the task has a very clear success criterion, OpenHands will do better. It is especially useful if you can define it in a way that can be verified programmatically, like making sure that all of the tests pass or test coverage gets above a certain value using a particular program. But even when you don't have something like that, you can just provide a checklist of things that need to be done. -- **Highly Repetitive Tasks:** These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create "[skills](TODO)" that clearly describe your policies about how to perform these tasks, and improve the skills over time. +- **Highly Repetitive Tasks:** These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create "[skills](/overview/skills)" that clearly describe your policies about how to perform these tasks, and improve the skills over time. - **Helping Answer Questions:** OpenHands agents are generally pretty good at answering questions about code bases, so you can feel free to ask them when you don't understand how something works. They can explore the code base and understand it deeply before providing an answer. - **Checking the Correctness of Library/Backend Code:** when agents work, they can run code, and they are particularly good at checking whether libraries or backend code works well. - **Reading Logs and Understanding Errors:** Agents can read blogs from GitHub or monitoring software and understand what is going wrong with your service in a live production setting. They're actually quite good at filtering through large amounts of data, especially if pushed in the correct direction. From 5729ad5171b1edc65735b0ca8e2eb5e73faaf871 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 18:16:48 +0000 Subject: [PATCH 19/19] Address neubig's review comments: remove hypothetical GitHub actions and fix broken link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace hypothetical openhands/review-action@v1 and openhands/triage-action@v1 with links to real SDK documentation for GitHub workflows - Update CI/CD Integration section to link to actual composite actions from software-agent-sdk repository - Fix broken link in dependency-upgrades.mdx: /openhands/usage/admin/security → /sdk/guides/security Co-authored-by: openhands --- .../essential-guidelines/sdlc-integration.mdx | 183 +++--------------- .../usage/use-cases/dependency-upgrades.mdx | 2 +- 2 files changed, 25 insertions(+), 160 deletions(-) diff --git a/openhands/usage/essential-guidelines/sdlc-integration.mdx b/openhands/usage/essential-guidelines/sdlc-integration.mdx index 1a33a84d..b56e3eb5 100644 --- a/openhands/usage/essential-guidelines/sdlc-integration.mdx +++ b/openhands/usage/essential-guidelines/sdlc-integration.mdx @@ -117,154 +117,37 @@ Prepare for production deployment: ## CI/CD Integration +OpenHands can be integrated into your CI/CD pipelines through the [Software Agent SDK](/sdk/index). Rather than using hypothetical actions, you can build powerful, customized workflows using real, production-ready tools. + ### GitHub Actions Integration -Integrate OpenHands into your GitHub workflows: +The Software Agent SDK provides composite GitHub Actions for common workflows: -```yaml -# .github/workflows/openhands-assist.yml -name: OpenHands Assist +- **[Automated PR Review](/openhands/usage/use-cases/code-review)** - Automatically review pull requests with inline comments +- **[SDK GitHub Workflows Guide](/sdk/guides/github-workflows/pr-review)** - Build custom GitHub workflows with the SDK -on: - issues: - types: [opened, labeled] - pull_request: - types: [opened, synchronize] - issue_comment: - types: [created] +For example, to set up automated PR reviews, see the [Automated Code Review](/openhands/usage/use-cases/code-review) guide which uses the real `OpenHands/software-agent-sdk/.github/actions/pr-review` composite action. -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 }} +### What You Can Automate - 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 }} -``` +Using the SDK, you can create GitHub Actions workflows to: -**Automated PR checks:** -- Code review on every PR -- Test coverage verification -- Security scanning -- Documentation checks +1. **Automatic code review** when a PR is opened +2. **Automatically update docs** weekly when new functionality is added +3. **Diagnose errors** that have appeared in monitoring software such as DataDog and automatically send analyses and improvements +4. **Manage TODO comments** and track technical debt +5. **Assign reviewers** based on code ownership patterns -### GitLab CI Integration +### Getting Started -```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 -``` +To integrate OpenHands into your CI/CD: -### 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' - } - } -} -``` +1. Review the [SDK Getting Started guide](/sdk/getting-started) +2. Explore the [GitHub Workflows examples](/sdk/guides/github-workflows/pr-review) +3. Set up your `LLM_API_KEY` as a repository secret +4. Use the provided composite actions or build custom workflows -### 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 -``` - -### Continuous Integration - -It is possible to use OpenHands not only through our GUI and CLI, but also through integrations into GitHub, GitLab, and BitBucket. - -This allows you to create actions to: - -1. Do automatic code review when a PR is opened -2. Automatically update docs weekly when new functionality is added -3. Diagnose errors that have appeared in monitoring software such as DataDog and automatically send analyses and improvements - -See the relevant links for examples. +See the [Use Cases](/openhands/usage/use-cases/code-review) section for complete examples of production-ready integrations. ## Team Workflows @@ -482,26 +365,8 @@ jobs: ### Event-Triggered Workflows -Respond to specific events: - -```yaml -# Respond to new issues -on: - issues: - types: [opened] +You can build custom event-triggered workflows using the Software Agent SDK. For example, the [Incident Triage](/openhands/usage/use-cases/incident-triage) use case shows how to automatically analyze and respond to issues. -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 -``` +For more event-driven automation patterns, see: +- [SDK GitHub Workflows Guide](/sdk/guides/github-workflows/pr-review) - Build custom workflows triggered by GitHub events +- [GitHub Action Integration](/openhands/usage/run-openhands/github-action) - Use the OpenHands resolver for issue triage diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index 10795fc2..7dad9000 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -280,5 +280,5 @@ addressing breaking changes in the correct order. ## Related Resources - [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities -- [Security](/openhands/usage/admin/security) - Security best practices +- [Security Guide](/sdk/guides/security) - Security best practices for AI agents - [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts