OpenHands / OpenHands/software-agent-sdk

Define design-doc expectations for deep, high-risk PRs

Open
#4,950 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement ready-for-dev
Dominant language
Python
Stars
1.1k
Forks
539
Avg merge
1d 19h
Merged PRs (30d)
137

Description

Desired Behavior

The SDK repository's code-review guide should ask for a concise design doc when a deep, high-risk SDK or Agent Server change cannot be evaluated efficiently from the diff, while avoiding unnecessary documentation for small or self-explanatory changes.

The policy must also account for .pr/ cleanup: an automated approval must not remove the only design artifact before a human maintainer has had the opportunity to review it.

Acceptance Criteria

  • Deep, high-risk PRs without adequate design context receive a COMMENT review instead of automated approval.
  • Low-risk, trivial, generated, or self-explanatory changes are not blocked solely by design-doc absence or line count.
  • An equivalent PR-description write-up has clear minimum content: intent, important before/after behavior or API shape, compatibility/risk, and grounded code references.
  • A .pr/ design doc remains available through the human review decision, or equivalent persistent context is present in the PR description before automated approval triggers cleanup.
  • The guidance remains consistent with the SDK repository's APPROVE-or-COMMENT policy and eval-risk rules.

This issue was created by an AI agent (OpenHands) on behalf of @enyst.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the SDK repository's code-review guide and the .pr/ cleanup workflow, then trace the existing APPROVE-or-COMMENT and eval-risk guidance. Update the documented expectations so high-risk changes require sufficient design context while trivial changes are not blocked. Done means the acceptance criteria are covered and design context remains available through human review.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
67/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.