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/25] 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/25] 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/25] 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/25] 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/25] 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 a921ff2158204bf1613ff2d7919daeddccd2e47c Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 5 Feb 2026 16:11:36 +0000 Subject: [PATCH 06/25] docs: Update code review documentation with PR review workflow - Rewrite code-review.mdx to document the automated PR review workflow - Explain how the workflow uses the Software Agent SDK with /codereview and /github-pr-review skills - Add Quick Start guide with step-by-step setup instructions - Document customization options including repo-specific review guidelines - Add security considerations and troubleshooting sections - Remove TODO- prefix from title Closes #297 --- openhands/usage/use-cases/code-review.mdx | 581 +++++++++------------- 1 file changed, 244 insertions(+), 337 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 1e9ca0a2..162a2254 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -1,408 +1,315 @@ --- -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`** or **`/codereview-roasted`**: Analyzes code for quality, security, and best practices + - **`/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`) | Pragmatic, constructive feedback focusing on code quality, security, and best practices | Day-to-day code reviews | +| **Roasted** (`/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 + ```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 + env: + LLM_MODEL: anthropic/claude-sonnet-4-5-20250929 + # Review style: 'standard' for pragmatic review, 'roasted' for Linus-style + REVIEW_STYLE: standard + PR_NUMBER: ${{ github.event.pull_request.number }} + PR_TITLE: ${{ github.event.pull_request.title }} + PR_BODY: ${{ github.event.pull_request.body }} + PR_BASE_BRANCH: ${{ github.event.pull_request.base.ref }} + PR_HEAD_BRANCH: ${{ github.event.pull_request.head.ref }} + REPO_NAME: ${{ github.repository }} + steps: + - name: Checkout software-agent-sdk repository + uses: actions/checkout@v5 + with: + repository: OpenHands/software-agent-sdk + path: software-agent-sdk + + - name: Checkout PR repository + uses: actions/checkout@v5 + with: + repository: ${{ github.event.pull_request.head.repo.full_name }} + ref: ${{ github.event.pull_request.head.ref }} + fetch-depth: 0 + persist-credentials: false + path: pr-repo + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: '3.12' + + - name: Install uv + uses: astral-sh/setup-uv@v7 + with: + enable-cache: true + + - name: Install GitHub CLI + run: sudo apt-get update && sudo apt-get install -y gh + + - name: Install OpenHands dependencies + run: | + uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools + + - name: Run PR review + env: + LLM_API_KEY: ${{ secrets.LLM_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + cd pr-repo + uv run python ../software-agent-sdk/examples/03_github_workflows/02_pr_review/agent_script.py + ``` + -Identify potential bugs before they ship: + + 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)) + -``` -Analyze the code changes for potential bugs: + + 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` + -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 + + Open a PR and either: + - Add the `review-this` label, OR + - Request `openhands-agent` as a reviewer + + -Provide specific line numbers and explanations for each issue found. -``` +## Customization -**Common bug patterns detected:** +### Repository-Specific Review Guidelines - - - ```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 - ``` - - +Create custom review guidelines for your repository by adding a skill file at `.openhands/skills/code-review.md`: -## Review Assistance +```markdown +--- +name: code-review +description: Custom code review guidelines for this repository +triggers: +- /codereview +--- -### Generating Review Comments +# Repository Code Review Guidelines -Get detailed review comments for a PR: +You are reviewing code for [Your Project Name]. Follow these guidelines: -``` -Generate code review comments for this pull request: +## Review Decisions -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 +### When to APPROVE +- Configuration changes following existing patterns +- Documentation-only changes +- Test-only changes without production code changes +- Simple additions following established conventions -Format the output as GitHub review comments. -``` +### When to COMMENT +- Issues that need attention (bugs, security concerns) +- Suggestions for improvement +- Questions about design decisions -**Example output:** +## Core Principles -``` -### src/api/users.py, line 45 -**Severity**: Major +1. **[Your Principle 1]**: Description +2. **[Your Principle 2]**: Description -**Issue**: SQL injection vulnerability +## What to Check -The user input is interpolated directly into the SQL query without sanitization. +- **[Category 1]**: What to look for +- **[Category 2]**: What to look for -**Current code:** -query = f"SELECT * FROM users WHERE id = {user_id}" +## Repository Conventions -**Suggested fix:** -query = "SELECT * FROM users WHERE id = %s" -cursor.execute(query, (user_id,)) +- Use [your linter] for style checking +- Follow [your style guide] +- Tests should be in [your test directory] ``` -### Identifying Potential Issues + +The skill file must use `/codereview` as the trigger to override the default review behavior. + -Proactively find issues that might cause problems: +### Workflow Configuration -``` -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 +Customize the workflow by modifying the `env` section: -Rank issues by risk and effort to fix. +```yaml +env: + # 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 ``` -### Suggesting Improvements - -Get suggestions for making code better: +### Trigger Customization -``` -Suggest improvements for the code in this PR: +Modify when reviews are triggered by editing the workflow conditions: -Focus on: -1. Cleaner, more idiomatic code -2. Better abstractions -3. Improved readability -4. Performance optimizations -5. More comprehensive testing -6. Enhanced documentation +```yaml +# Only trigger on label (disable auto-review on PR open) +if: github.event.label.name == 'review-this' -For each suggestion, explain the benefit and show before/after code. -``` +# Only trigger when specific reviewer is requested +if: github.event.requested_reviewer.login == 'openhands-agent' -**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) +# Trigger on all PRs (including drafts) +if: | + github.event.action == 'opened' || + github.event.action == 'synchronize' ``` -## Integration - -### GitHub Pull Request Integration +## Security Considerations -OpenHands integrates with GitHub for automated PR reviews: +The workflow uses `pull_request_target` to safely handle fork PRs: -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 +- **Secrets are protected**: The workflow runs in the base repository context +- **PR code is isolated**: The PR branch is checked out without persisting credentials +- **Maintainer control**: Only users with write access can trigger reviews via labels or reviewer requests +- **First-time contributors**: PRs from first-time contributors require manual trigger for safety -**Automatic review workflow:** + +Always review PRs from unknown contributors before triggering automated reviews to ensure the code is safe to analyze. + -```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 +## What Gets Reviewed -### CI/CD Pipeline Integration - -Add code review to your CI/CD pipeline: +The agent analyzes your code changes across multiple dimensions: - - ```yaml - - name: OpenHands Review - uses: openhands/review-action@v1 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - fail-on: critical # Fail CI if critical issues found - ``` + + - Complexity and nesting depth + - Code duplication + - Function size and responsibility + - Naming clarity + - Documentation completeness - - ```yaml - code_review: - stage: review - script: - - openhands review --format=gitlab - allow_failure: false - ``` + + - Input validation + - SQL injection risks + - Hardcoded secrets + - Authentication/authorization issues + - Cryptographic misuse - - ```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 - ``` + + - Error handling + - Resource cleanup + - Type safety + - Testing coverage + - Backward compatibility -## 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 +## Example Review Output -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 - -### Security-Focused Review +Here's what a typical review comment looks like: ``` -Perform a security review of this PR: +🟠 Important: This function doesn't handle the case where `user` is None, +which could cause an AttributeError on line 45. -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. +```suggestion +if user is None: + raise ValueError("User cannot be None") +return user.name ``` - -### 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 -``` +The agent uses GitHub's suggestion syntax, allowing you to apply fixes with a single click. + +## 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 +- [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 72bf01875a4c420feb2ed3aca289ca0f761eccbb Mon Sep 17 00:00:00 2001 From: Calvin Smith Date: Thu, 5 Feb 2026 12:00:39 -0700 Subject: [PATCH 07/25] 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 08/25] 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 09/25] 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 10/25] 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 11/25] 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 12/25] 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 96e04d10aac9860fde64724fdcb505cc87f728e2 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 16:50:43 +0000 Subject: [PATCH 13/25] docs: Update code review docs to use new composite GitHub Action Update the code review documentation to reflect the new composite GitHub Action from software-agent-sdk PR #1927. The changes include: - Simplified Quick Start workflow using the composite action - Added new 'Composite Action' section with action inputs table - Updated Customization section to show input-based configuration - Removed manual setup steps (Python, uv, dependencies) that are now handled by the composite action Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 104 ++++++++++------------ 1 file changed, 46 insertions(+), 58 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 162a2254..dc039876 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -68,56 +68,14 @@ Choose between two review styles: github.event.label.name == 'review-this' || github.event.requested_reviewer.login == 'openhands-agent' runs-on: ubuntu-latest - env: - LLM_MODEL: anthropic/claude-sonnet-4-5-20250929 - # Review style: 'standard' for pragmatic review, 'roasted' for Linus-style - REVIEW_STYLE: standard - PR_NUMBER: ${{ github.event.pull_request.number }} - PR_TITLE: ${{ github.event.pull_request.title }} - PR_BODY: ${{ github.event.pull_request.body }} - PR_BASE_BRANCH: ${{ github.event.pull_request.base.ref }} - PR_HEAD_BRANCH: ${{ github.event.pull_request.head.ref }} - REPO_NAME: ${{ github.repository }} steps: - - name: Checkout software-agent-sdk repository - uses: actions/checkout@v5 + - name: Run PR Review + uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main with: - repository: OpenHands/software-agent-sdk - path: software-agent-sdk - - - name: Checkout PR repository - uses: actions/checkout@v5 - with: - repository: ${{ github.event.pull_request.head.repo.full_name }} - ref: ${{ github.event.pull_request.head.ref }} - fetch-depth: 0 - persist-credentials: false - path: pr-repo - - - name: Set up Python - uses: actions/setup-python@v6 - with: - python-version: '3.12' - - - name: Install uv - uses: astral-sh/setup-uv@v7 - with: - enable-cache: true - - - name: Install GitHub CLI - run: sudo apt-get update && sudo apt-get install -y gh - - - name: Install OpenHands dependencies - run: | - uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools - - - name: Run PR review - env: - LLM_API_KEY: ${{ secrets.LLM_API_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - cd pr-repo - uv run python ../software-agent-sdk/examples/03_github_workflows/02_pr_review/agent_script.py + llm-model: anthropic/claude-sonnet-4-5-20250929 + review-style: standard + llm-api-key: ${{ secrets.LLM_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` @@ -141,6 +99,31 @@ Choose between two review styles: +## Composite Action + +The workflow uses a reusable composite action from the Software Agent SDK that handles all the setup automatically: + +- Checking out the SDK at the specified version +- Setting up Python and dependencies +- Running the PR review agent +- Uploading logs as artifacts + +### Action Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `llm-model` | LLM model to use | No | `anthropic/claude-sonnet-4-5-20250929` | +| `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 | - | + + +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. + + ## Customization ### Repository-Specific Review Guidelines @@ -195,18 +178,23 @@ The skill file must use `/codereview` as the trigger to override the default rev ### Workflow Configuration -Customize the workflow by modifying the `env` section: +Customize the workflow by modifying the action inputs: ```yaml -env: - # 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 +- 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 }} ``` ### Trigger Customization From b76480e360cef01ba372605e7cc2e4646b04bcd1 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 16:57:03 +0000 Subject: [PATCH 14/25] fix: Remove broken link to non-existent security page Co-authored-by: openhands --- openhands/usage/use-cases/dependency-upgrades.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index d602b5ea..aa6c219a 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -381,5 +381,4 @@ 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 - [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) - Write effective prompts From 0c7074f6661d9edaf5393df270924c63910c348c Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:27:07 +0000 Subject: [PATCH 15/25] docs: Bring changes from PR #306 - customizable code review and composite action - Add 'Customizable' feature to Features section - Add new 'Customizing the Code Review' section with: - How custom skills work - Example custom code review skill - Benefits of custom skills - Update Reference Workflow to use simplified composite action - Add Action Inputs table documenting all available inputs - Add link to Composite Action in Related Files Co-authored-by: openhands --- sdk/guides/github-workflows/pr-review.mdx | 229 ++++++++++++---------- 1 file changed, 122 insertions(+), 107 deletions(-) diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index 6fe37a4c..03a89ffb 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -16,15 +16,107 @@ Automatically review pull requests, providing feedback on code quality, security The reference workflow triggers on either the "review-this" label or when the openhands-agent account is requested as a reviewer. In OpenHands organization repositories, openhands-agent has access, so this works as-is. In your own repositories, requesting openhands-agent will only work if that account is added as a collaborator or is part of a team with access. If you don't plan to grant access, use the label trigger instead, or change the condition to a reviewer handle that exists in your repo. +## Quick Start + +```bash +# 1. Copy workflow to your repository +cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml + +# 2. Configure secrets in GitHub Settings → Secrets +# Add: LLM_API_KEY + +# 3. (Optional) Create a "review-this" label in your repository +# Go to Issues → Labels → New label +# You can also trigger reviews by requesting "openhands-agent" as a reviewer +``` + +## Features + +- **Fast Reviews** - Results posted on the PR in only 2 or 3 minutes +- **Comprehensive Analysis** - Analyzes the changes given the repository context. Covers code quality, security, best practices +- **GitHub Integration** - Posts comments directly to the PR +- **Customizable** - Add your own code review guidelines without forking + +## Security + +- Users with write access (maintainers) can trigger reviews by requesting `openhands-agent` as a reviewer or adding the `review-this` label. +- Maintainers need to read the PR to make sure it's safe to run. + +## Customizing the Code Review + +Instead of forking the `agent_script.py`, you can customize the code review behavior by adding a `.openhands/skills/code-review.md` file to your repository. This is the **recommended approach** for customization. + +### How It Works + +The PR review agent uses skills from the [OpenHands/skills](https://github.com/OpenHands/skills) repository by default. When you add a `.openhands/skills/code-review.md` file to your repository, it **overrides** the default skill with your custom guidelines. + +### Example: Custom Code Review Skill + +Create `.openhands/skills/code-review.md` in your repository: + +```markdown +--- +name: code-review +description: Custom code review guidelines for my project +triggers: +- /codereview +--- + +# My Project Code Review Guidelines + +You are a code reviewer for this project. Follow these guidelines: + +## Review Decisions + +- **APPROVE** straightforward changes (config updates, typo fixes, documentation) +- **COMMENT** when you have feedback or concerns + +## What to Check + +- Code follows our project conventions +- Tests are included for new functionality +- No security vulnerabilities introduced +- Documentation is updated if needed + +## Communication Style + +- Be direct and constructive +- Use GitHub suggestion syntax for code fixes +- Approve quickly when code is good +``` + +### Benefits of Custom Skills + +1. **No forking required**: Keep using the official SDK while customizing behavior +2. **Version controlled**: Your review guidelines live in your repository +3. **Easy updates**: SDK updates don't overwrite your customizations +4. **Team alignment**: Everyone uses the same review standards + + +See the [software-agent-sdk's own code-review skill](https://github.com/OpenHands/software-agent-sdk/blob/main/.openhands/skills/code-review.md) for a complete example of a custom code review skill. + + +## Reference Workflow + + +This example is available on GitHub: [examples/03_github_workflows/02_pr_review/](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) + + ```yaml icon="yaml" expandable examples/03_github_workflows/02_pr_review/workflow.yml --- +# OpenHands PR Review Workflow +# # To set this up: # 1. Copy this file to .github/workflows/pr-review.yml in your repository -# 2. Add your LLM_API_KEY to the repository secrets -# 3. Commit this file to your repository -# 4. Trigger the review by either: +# 2. Add LLM_API_KEY to repository secrets +# 3. Customize the inputs below as needed +# 4. Commit this file to your repository +# 5. Trigger the review by either: # - Adding the "review-this" label to any PR, OR # - Requesting openhands-agent as a reviewer +# +# For more information, see: +# https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review name: PR Review by OpenHands on: @@ -44,122 +136,45 @@ jobs: github.event.label.name == 'review-this' || github.event.requested_reviewer.login == 'openhands-agent' runs-on: ubuntu-latest - env: - # Configuration (modify these values as needed) - LLM_MODEL: - LLM_BASE_URL: - # Review style: 'standard' for pragmatic review, 'roasted' for Linus-style - REVIEW_STYLE: standard - # PR context will be automatically provided by the agent script - PR_NUMBER: ${{ github.event.pull_request.number }} - PR_TITLE: ${{ github.event.pull_request.title }} - PR_BODY: ${{ github.event.pull_request.body }} - PR_BASE_BRANCH: ${{ github.event.pull_request.base.ref }} - PR_HEAD_BRANCH: ${{ github.event.pull_request.head.ref }} - REPO_NAME: ${{ github.repository }} steps: - - name: Checkout software-agent-sdk repository + - name: Checkout for composite action uses: actions/checkout@v4 with: repository: OpenHands/software-agent-sdk - path: software-agent-sdk - - - name: Checkout PR repository - uses: actions/checkout@v4 - with: - # Fetch the full history to get the diff - fetch-depth: 0 - path: pr-repo - # Check out the feature branch so agent can inspect the PR changes - ref: ${{ github.event.pull_request.head.ref }} - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.12' + # Use a specific version tag or branch (e.g., 'v1.0.0' or 'main') + ref: main + sparse-checkout: .github/actions/pr-review - - name: Install uv - uses: astral-sh/setup-uv@v6 - with: - enable-cache: true - - - name: Install GitHub CLI - run: | - # Install GitHub CLI for posting review comments - sudo apt-get update - sudo apt-get install -y gh - - - name: Install OpenHands dependencies - run: | - # Install OpenHands SDK and tools from local checkout - uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools - - - name: Check required configuration - env: - LLM_API_KEY: ${{ secrets.LLM_API_KEY }} - run: | - if [ -z "$LLM_API_KEY" ]; then - echo "Error: LLM_API_KEY secret is not set." - exit 1 - fi - - echo "PR Number: $PR_NUMBER" - echo "PR Title: $PR_TITLE" - echo "Repository: $REPO_NAME" - echo "LLM model: $LLM_MODEL" - if [ -n "$LLM_BASE_URL" ]; then - echo "LLM base URL: $LLM_BASE_URL" - fi - - - name: Run PR review - env: - LLM_API_KEY: ${{ secrets.LLM_API_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - # Change to the PR repository directory so agent can analyze the code - cd pr-repo - - # Run the PR review script from the software-agent-sdk checkout - uv run python ../software-agent-sdk/examples/03_github_workflows/02_pr_review/agent_script.py - - - name: Upload logs as artifact - uses: actions/upload-artifact@v4 - if: always() + - name: Run PR Review + uses: ./.github/actions/pr-review with: - name: openhands-pr-review-logs - path: | - *.log - output/ - retention-days: 7 + # LLM configuration + llm-model: anthropic/claude-sonnet-4-5-20250929 + llm-base-url: '' + # Review style: roasted (other option: standard) + review-style: roasted + # SDK version to use (version tag or branch name) + sdk-version: main + # Secrets + llm-api-key: ${{ secrets.LLM_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` -## Quick Start +### Action Inputs -```bash -# 1. Copy workflow to your repository -cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml - -# 2. Configure secrets in GitHub Settings → Secrets -# Add: LLM_API_KEY - -# 3. (Optional) Create a "review-this" label in your repository -# Go to Issues → Labels → New label -# You can also trigger reviews by requesting "openhands-agent" as a reviewer -``` - -## Features - -- **Fast Reviews** - Results posted on the PR in only 2 or 3 minutes -- **Comprehensive Analysis** - Analyzes the changes given the repository context. Covers code quality, security, best practices -- **GitHub Integration** - Posts comments directly to the PR - -## Security - -- Users with write access (maintainers) can trigger reviews by requesting `openhands-agent` as a reviewer or adding the `review-this` label. -- Maintainers need to read the PR to make sure it's safe to run. +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `llm-model` | LLM model to use | No | `anthropic/claude-sonnet-4-5-20250929` | +| `llm-base-url` | LLM base URL (optional) | 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 | - | ## Related Files - [Agent Script](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/03_github_workflows/02_pr_review/agent_script.py) - [Workflow File](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/03_github_workflows/02_pr_review/workflow.yml) - [Prompt Template](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/03_github_workflows/02_pr_review/prompt.py) +- [Composite Action](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/actions/pr-review/action.yml) From ff4f378078eca1d68ddc3a912bad3121f09affcd Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:31:13 +0000 Subject: [PATCH 16/25] docs: Add composite action link and SDK skill example reference to code-review.mdx - Add link to Composite Action in Related Resources section - Add reference to software-agent-sdk's code-review skill as example Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index dc039876..682eea2a 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -173,7 +173,7 @@ You are reviewing code for [Your Project Name]. Follow these guidelines: ``` -The skill file must use `/codereview` as the trigger to override the default review behavior. +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/.openhands/skills/code-review.md) for a complete example. ### Workflow Configuration @@ -298,6 +298,7 @@ The agent uses GitHub's suggestion syntax, allowing you to apply fixes with a si ## Related Resources - [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 f6f529f3a735a1d97dd631de06dc8540adaf51d3 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:33:49 +0000 Subject: [PATCH 17/25] docs: Link skills to OpenHands/skills repo in code-review.mdx - Add links to /codereview skill in OpenHands/skills repo - Add links to /codereview-roasted skill in OpenHands/skills repo - Add links to /github-pr-review skill in OpenHands/skills repo Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 682eea2a..c1836e11 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -25,8 +25,8 @@ The PR review workflow uses the OpenHands Software Agent SDK to analyze your cod - `openhands-agent` is requested as a reviewer 2. **Analysis**: The agent receives the complete PR diff and uses two skills: - - **`/codereview`** or **`/codereview-roasted`**: Analyzes code for quality, security, and best practices - - **`/github-pr-review`**: Posts structured inline comments via the GitHub API + - [**`/codereview`**](https://github.com/OpenHands/skills/tree/main/skills/codereview) or [**`/codereview-roasted`**](https://github.com/OpenHands/skills/tree/main/skills/codereview-roasted): Analyzes code for quality, security, and best practices + - [**`/github-pr-review`**](https://github.com/OpenHands/skills/tree/main/skills/github-pr-review): Posts structured inline comments via the GitHub API 3. **Output**: Review comments are posted directly on the PR with: - Priority labels (🔴 Critical, 🟠 Important, 🟡 Suggestion, 🟢 Nit) @@ -39,8 +39,8 @@ Choose between two review styles: | Style | Description | Best For | |-------|-------------|----------| -| **Standard** (`/codereview`) | Pragmatic, constructive feedback focusing on code quality, security, and best practices | Day-to-day code reviews | -| **Roasted** (`/codereview-roasted`) | Linus Torvalds-style brutally honest review emphasizing "good taste", data structures, and simplicity | Critical code paths, learning opportunities | +| **Standard** ([`/codereview`](https://github.com/OpenHands/skills/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/skills/tree/main/skills/codereview-roasted)) | Linus Torvalds-style brutally honest review emphasizing "good taste", data structures, and simplicity | Critical code paths, learning opportunities | ## Quick Start From 97b03e3db2ef0f4d459e681c9791b5ca5009e12c Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:36:28 +0000 Subject: [PATCH 18/25] docs: Mark llm-model as required in Action Inputs table Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 2 +- sdk/guides/github-workflows/pr-review.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index c1836e11..5f252024 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -112,7 +112,7 @@ The workflow uses a reusable composite action from the Software Agent SDK that h | Input | Description | Required | Default | |-------|-------------|----------|---------| -| `llm-model` | LLM model to use | No | `anthropic/claude-sonnet-4-5-20250929` | +| `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` | diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index 03a89ffb..ddb28285 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -164,7 +164,7 @@ jobs: | Input | Description | Required | Default | |-------|-------------|----------|---------| -| `llm-model` | LLM model to use | No | `anthropic/claude-sonnet-4-5-20250929` | +| `llm-model` | LLM model to use | Yes | - | | `llm-base-url` | LLM base URL (optional) | No | `''` | | `review-style` | Review style: 'standard' or 'roasted' | No | `roasted` | | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | From 23696659fb2779d85db825697e422b5b94563ee2 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:39:01 +0000 Subject: [PATCH 19/25] docs: Replace 'What Gets Reviewed' with real example PR reviews - Remove generic 'What Gets Reviewed' section with tabs - Replace 'Example Review Output' with table of real PR examples from software-agent-sdk - Link to PRs #1927, #1916, #1904, #1889 showing different review styles Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 50 ++++------------------- 1 file changed, 8 insertions(+), 42 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 5f252024..a2f97465 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -227,50 +227,16 @@ The workflow uses `pull_request_target` to safely handle fork PRs: Always review PRs from unknown contributors before triggering automated reviews to ensure the code is safe to analyze. -## What Gets Reviewed - -The agent analyzes your code changes across multiple dimensions: - - - - - Complexity and nesting depth - - Code duplication - - Function size and responsibility - - Naming clarity - - Documentation completeness - - - - Input validation - - SQL injection risks - - Hardcoded secrets - - Authentication/authorization issues - - Cryptographic misuse - - - - Error handling - - Resource cleanup - - Type safety - - Testing coverage - - Backward compatibility - - - -## Example Review Output - -Here's what a typical review comment looks like: +## Example Reviews -``` -🟠 Important: This function doesn't handle the case where `user` is None, -which could cause an AttributeError on line 45. - -```suggestion -if user is None: - raise ValueError("User cannot be None") -return user.name -``` -``` +See real automated reviews in action on the OpenHands Software Agent SDK repository: -The agent uses GitHub's suggestion syntax, allowing you to apply fixes with a single click. +| PR | Description | Review Highlights | +|----|-------------|-------------------| +| [#1927](https://github.com/OpenHands/software-agent-sdk/pull/1927) | Composite GitHub Action refactor | Comprehensive review with 🔴 Critical, 🟠 Important, and 🟡 Suggestion labels | +| [#1916](https://github.com/OpenHands/software-agent-sdk/pull/1916) | Add example for reconstructing messages | Critical issues flagged with clear explanations | +| [#1904](https://github.com/OpenHands/software-agent-sdk/pull/1904) | Update code-review skill guidelines | APPROVED review highlighting key strengths | +| [#1889](https://github.com/OpenHands/software-agent-sdk/pull/1889) | Fix tmux race condition | Technical review of concurrency fix with dual-lock strategy analysis | ## Troubleshooting From cb9e733e7404c010323e2c0a78acf7f35a15617c Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:41:39 +0000 Subject: [PATCH 20/25] docs: Link directly to review comments instead of PR pages Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index a2f97465..63eb2d65 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -233,10 +233,10 @@ See real automated reviews in action on the OpenHands Software Agent SDK reposit | PR | Description | Review Highlights | |----|-------------|-------------------| -| [#1927](https://github.com/OpenHands/software-agent-sdk/pull/1927) | Composite GitHub Action refactor | Comprehensive review with 🔴 Critical, 🟠 Important, and 🟡 Suggestion labels | -| [#1916](https://github.com/OpenHands/software-agent-sdk/pull/1916) | Add example for reconstructing messages | Critical issues flagged with clear explanations | -| [#1904](https://github.com/OpenHands/software-agent-sdk/pull/1904) | Update code-review skill guidelines | APPROVED review highlighting key strengths | -| [#1889](https://github.com/OpenHands/software-agent-sdk/pull/1889) | Fix tmux race condition | Technical review of concurrency fix with dual-lock strategy analysis | +| [#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 From de9459d3b7f9930b508a3f5295c1a2ae4ef96800 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:48:17 +0000 Subject: [PATCH 21/25] docs: Add security warning about API key exfiltration risk from fork PRs - Add 'API Key Protection' subsection explaining the potential risk - Document how SDK secrets mitigate the risk - Add best practices: review PRs first, use separate API keys, monitor usage - Link to SDK secrets documentation Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 63eb2d65..15fabdc9 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -223,10 +223,18 @@ The workflow uses `pull_request_target` to safely handle fork PRs: - **Maintainer control**: Only users with write access can trigger reviews via labels or reviewer requests - **First-time contributors**: PRs from first-time contributors require manual trigger for safety +### API Key Protection + -Always review PRs from unknown contributors before triggering automated reviews to ensure the code is safe to analyze. +**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 risk, the PR review workflow passes API keys as [SDK secrets](/sdk/guides/secrets) rather than environment variables. This prevents the agent from directly accessing or exposing these credentials during code execution. However, you should still: + +1. **Review PRs before triggering reviews** - Always inspect code from unknown contributors before adding the `review-this` label or requesting a review +2. **Use separate API keys** - Consider using a dedicated API key for automated reviews with appropriate rate limits +3. **Monitor usage** - Keep an eye on your LLM API usage for unexpected spikes + ## Example Reviews See real automated reviews in action on the OpenHands Software Agent SDK repository: From a5d893bf0d7c2e6da26336101904c0a1ef462dee Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 17:51:23 +0000 Subject: [PATCH 22/25] docs: Simplify security considerations section - Summarize pull_request_target usage in one sentence - Keep warning about API key exfiltration risk concise - Remove prescriptive best practices list Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 15fabdc9..f0f5e6e9 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -216,24 +216,13 @@ if: | ## Security Considerations -The workflow uses `pull_request_target` to safely handle fork PRs: - -- **Secrets are protected**: The workflow runs in the base repository context -- **PR code is isolated**: The PR branch is checked out without persisting credentials -- **Maintainer control**: Only users with write access can trigger reviews via labels or reviewer requests -- **First-time contributors**: PRs from first-time contributors require manual trigger for safety - -### API Key Protection +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 risk, the PR review workflow passes API keys as [SDK secrets](/sdk/guides/secrets) rather than environment variables. This prevents the agent from directly accessing or exposing these credentials during code execution. However, you should still: - -1. **Review PRs before triggering reviews** - Always inspect code from unknown contributors before adding the `review-this` label or requesting a review -2. **Use separate API keys** - Consider using a dedicated API key for automated reviews with appropriate rate limits -3. **Monitor usage** - Keep an eye on your LLM API usage for unexpected spikes +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 From 8a303656031d10b094d3cdd7cdd2272ea1acfbb8 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Mon, 9 Feb 2026 01:51:41 +0800 Subject: [PATCH 23/25] Update sdk/guides/github-workflows/pr-review.mdx Co-authored-by: Engel Nyst --- sdk/guides/github-workflows/pr-review.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index ddb28285..da5a8173 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -44,7 +44,7 @@ cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-r ## Customizing the Code Review -Instead of forking the `agent_script.py`, you can customize the code review behavior by adding a `.openhands/skills/code-review.md` file to your repository. This is the **recommended approach** for customization. +Instead of forking the `agent_script.py`, you can customize the code review behavior by adding a `.agents/skills/code-review.md` file to your repository. This is the **recommended approach** for customization. ### How It Works From 77f1e60c8379ed16bb2db1d3072c73afe928e16f Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Mon, 9 Feb 2026 01:51:49 +0800 Subject: [PATCH 24/25] Update openhands/usage/use-cases/code-review.mdx Co-authored-by: Engel Nyst --- openhands/usage/use-cases/code-review.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index f0f5e6e9..d5119433 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -173,7 +173,7 @@ You are reviewing code for [Your Project Name]. Follow these guidelines: ``` -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/.openhands/skills/code-review.md) for a complete example. +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. ### Workflow Configuration From b4f2981f0dfd4575874eb3fb356ab90a5a85fe29 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Mon, 9 Feb 2026 01:54:43 +0800 Subject: [PATCH 25/25] Update openhands/usage/use-cases/code-review.mdx Co-authored-by: Engel Nyst --- openhands/usage/use-cases/code-review.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index d5119433..65a25504 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -128,7 +128,7 @@ Use `sdk-version` to pin to a specific version tag (e.g., `v1.0.0`) for producti ### Repository-Specific Review Guidelines -Create custom review guidelines for your repository by adding a skill file at `.openhands/skills/code-review.md`: +Create custom review guidelines for your repository by adding a skill file at `.agents/skills/code-review.md`: ```markdown ---