Skip to content

Commit 77db2ac

Browse files
enystenyst
authored
Merge branch 'main' into fix/ws-rest-event-sync
2 parents b67f459 + 12cb484 commit 77db2ac

File tree

16 files changed

+1699
-76
lines changed

16 files changed

+1699
-76
lines changed

‎.agents/skills/code-review.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,53 @@ If there are significant issues, leave detailed comments explaining the concerns
6363
- **Breaking Changes**: API changes affecting users, removed public fields/methods, changed defaults
6464
- **Code Quality**: Code duplication, missing comments for non-obvious decisions, inline imports (unless necessary for circular deps)
6565
- **Repository Conventions**: Use `pyright` not `mypy`, put fixtures in `conftest.py`, avoid `sys.path.insert` hacks
66+
- **Event Type Deprecation**: Changes to event types (Pydantic models used in serialization) must handle deprecated fields properly
67+
68+
## Event Type Deprecation - Critical Review Checkpoint
69+
70+
When reviewing PRs that modify event types (e.g., `TextContent`, `Message`, `Event`, or any Pydantic model used in event serialization), **DO NOT APPROVE** until the following are verified:
71+
72+
### Required for Removing/Deprecating Fields
73+
74+
1. **Model validator present**: If a field is being removed from an event type with `extra="forbid"`, there MUST be a `@model_validator(mode="before")` that uses `handle_deprecated_model_fields()` to remove the deprecated field before validation. Otherwise, old events will fail to load.
75+
76+
2. **Tests for backward compatibility**: The PR MUST include tests that:
77+
- Load an old event format (with the deprecated field) successfully
78+
- Load a new event format (without the deprecated field) successfully
79+
- Verify both can be loaded in sequence (simulating mixed conversations)
80+
81+
3. **Test naming convention**: The version in the test name should be the **LAST version** where a particular event structure exists. For example, if `enable_truncation` was removed in v1.11.1, the test should be named `test_v1_10_0_...` (the last version with that field), not `test_v1_8_0_...` (when it was introduced). This avoids duplicate tests and clearly documents when a field was last present.
82+
83+
**Important**: Deprecated field handlers are **permanent** and should never be removed. They ensure old conversations can always be loaded.
84+
85+
### Example Pattern (Required)
86+
87+
```python
88+
from openhands.sdk.utils.deprecation import handle_deprecated_model_fields
89+
90+
class MyModel(BaseModel):
91+
model_config = ConfigDict(extra="forbid")
92+
93+
# Deprecated fields that are silently removed for backward compatibility
94+
# when loading old events. These are kept permanently.
95+
_DEPRECATED_FIELDS: ClassVar[tuple[str, ...]] = ("old_field_name",)
96+
97+
@model_validator(mode="before")
98+
@classmethod
99+
def _handle_deprecated_fields(cls, data: Any) -> Any:
100+
"""Remove deprecated fields for backward compatibility with old events."""
101+
return handle_deprecated_model_fields(data, cls._DEPRECATED_FIELDS)
102+
```
103+
104+
### Why This Matters
105+
106+
Production systems resume conversations that may contain events serialized with older SDK versions. If the SDK can't load old events, users will see errors like:
107+
108+
```
109+
pydantic_core.ValidationError: Extra inputs are not permitted
110+
```
111+
112+
**This is a production-breaking change.** Do not approve PRs that modify event types without proper backward compatibility handling and tests.
66113

67114
## What NOT to Comment On
68115

‎.agents/skills/feature-release-rollout/SKILL.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
name: feature-release-rollout
3+
description: This skill should be used when the user asks to "rollout a feature", "complete feature release", "propagate SDK feature", "track feature support", "what's missing for feature X", or mentions checking CLI/GUI/docs/blog support for SDK features. Guides agents through the multi-repository feature release workflow from SDK to docs to marketing.
4+
triggers:
5+
- rollout feature
6+
- feature release
7+
- propagate feature
8+
- feature support
9+
- complete release
10+
- docs for feature
11+
- blog for feature
12+
- CLI support
13+
- GUI support
14+
- what's missing
15+
---
16+
17+
# Feature Release Rollout
18+
19+
This skill guides the complete feature release workflow across the OpenHands ecosystem repositories.
20+
21+
## Overview
22+
23+
When a feature is implemented in the SDK, it may need propagation through several repositories:
24+
25+
1. **SDK** (`OpenHands/software-agent-sdk`) — Core feature implementation
26+
2. **CLI** (`OpenHands/OpenHands-CLI`) — Terminal interface support
27+
3. **GUI** (`OpenHands/OpenHands` frontend directory) — Web interface support
28+
4. **Docs** (`OpenHands/docs`) — Documentation updates (sdk/ folder)
29+
5. **Blog** (`OpenHands/growth-utils` blog-post/) — Marketing and announcements
30+
6. **Video** — Tutorial content (using ElevenLabs + Remotion)
31+
32+
## Workflow
33+
34+
### Phase 1: Feature Discovery
35+
36+
First, identify what feature(s) to analyze. The user may specify:
37+
- A release tag (e.g., `v1.9.0`)
38+
- A specific feature name
39+
- A PR or commit reference
40+
- A comparison between versions
41+
42+
**For release tags:**
43+
```bash
44+
# Clone SDK if not present
45+
git clone https://github.com/OpenHands/software-agent-sdk.git
46+
47+
# View release notes
48+
cd software-agent-sdk
49+
git log --oneline v1.8.0..v1.9.0 # Changes between versions
50+
git show v1.9.0 --stat # What changed in this release
51+
```
52+
53+
**For specific features:**
54+
Search the SDK codebase, examples, and changelog to understand the feature scope.
55+
56+
### Phase 2: Repository Analysis
57+
58+
Clone all relevant repositories to analyze current support:
59+
60+
```bash
61+
# Clone repositories (use GITHUB_TOKEN for authenticated access)
62+
git clone https://github.com/OpenHands/software-agent-sdk.git
63+
git clone https://github.com/OpenHands/OpenHands-CLI.git
64+
git clone https://github.com/OpenHands/OpenHands.git # Frontend in frontend/
65+
git clone https://github.com/OpenHands/docs.git
66+
git clone https://github.com/OpenHands/growth-utils.git
67+
```
68+
69+
For each feature, check support status:
70+
71+
| Repository | Check Location | What to Look For |
72+
|------------|---------------|------------------|
73+
| CLI | `openhands_cli/` | Feature flags, commands, TUI widgets |
74+
| GUI | `OpenHands/frontend/src/` | React components, API integrations |
75+
| Docs | `docs/sdk/` | Guide pages, API reference, examples |
76+
| Blog | `growth-utils/blog-post/posts/` | Announcement posts |
77+
78+
### Phase 3: Assess Feature Importance
79+
80+
Not all features warrant full rollout. Evaluate each feature:
81+
82+
**High Impact (full rollout recommended):**
83+
- New user-facing capabilities
84+
- Breaking changes or migrations
85+
- Major performance improvements
86+
- New integrations or tools
87+
88+
**Medium Impact (docs + selective support):**
89+
- New API methods or parameters
90+
- Configuration options
91+
- Developer experience improvements
92+
93+
**Low Impact (docs only or skip):**
94+
- Internal refactoring
95+
- Bug fixes
96+
- Minor enhancements
97+
98+
**Skip rollout for:**
99+
- Internal-only changes
100+
- Test improvements
101+
- Build/CI changes
102+
- Documentation typos
103+
104+
### Phase 4: Create Proposal
105+
106+
Generate a structured proposal for the user:
107+
108+
```markdown
109+
## Feature Rollout Proposal: [Feature Name]
110+
111+
### Feature Summary
112+
[Brief description of the feature and its value]
113+
114+
### Current Support Status
115+
| Component | Status | Notes |
116+
|-----------|--------|-------|
117+
| SDK | ✅ Implemented | [version/PR] |
118+
| CLI | ❌ Missing | [what's needed] |
119+
| GUI | ⚠️ Partial | [what's implemented vs needed] |
120+
| Docs | ❌ Missing | [suggested pages] |
121+
| Blog | ❌ Not started | [whether warranted] |
122+
| Video | ❌ Not started | [whether warranted] |
123+
124+
### Recommended Actions
125+
1. **CLI**: [specific implementation needed]
126+
2. **GUI**: [specific implementation needed]
127+
3. **Docs**: [pages to create/update]
128+
4. **Blog**: [recommended or not, with reasoning]
129+
5. **Video**: [recommended or not, with reasoning]
130+
131+
### Assessment
132+
- **Overall Priority**: [High/Medium/Low]
133+
- **Effort Estimate**: [days/hours per component]
134+
- **Dependencies**: [what must be done first]
135+
```
136+
137+
### Phase 5: User Confirmation
138+
139+
Wait for explicit user approval before proceeding. Ask:
140+
- Which components to implement
141+
- Priority ordering
142+
- Any modifications to the proposal
143+
144+
### Phase 6: Implementation
145+
146+
Only after user confirmation:
147+
148+
**Create GitHub Issues:**
149+
```bash
150+
# Create issue on relevant repo
151+
gh issue create --repo OpenHands/OpenHands-CLI \
152+
--title "Support [feature] in CLI" \
153+
--body "## Context\n[Feature description]\n\n## Implementation\n[Details]\n\n## Related\n- SDK: [link]\n- Docs: [link]"
154+
```
155+
156+
**Implementation order:**
157+
1. CLI/GUI support (can be parallel)
158+
2. Documentation (depends on 1)
159+
3. Blog post (depends on 2)
160+
4. Video (depends on 3)
161+
162+
## Repository-Specific Guidelines
163+
164+
### CLI (OpenHands/OpenHands-CLI)
165+
166+
- Check `AGENTS.md` for development guidelines
167+
- Use `uv` for dependency management
168+
- Run `make lint` and `make test` before commits
169+
- TUI components in `openhands_cli/tui/`
170+
- Snapshot tests for UI changes
171+
172+
### GUI (OpenHands/OpenHands frontend)
173+
174+
- Frontend in `frontend/` directory
175+
- React/TypeScript codebase
176+
- Run `npm run lint:fix && npm run build` in frontend/
177+
- Follow TanStack Query patterns for data fetching
178+
- i18n translations in `frontend/src/i18n/`
179+
180+
### Docs (OpenHands/docs)
181+
182+
- SDK docs in `sdk/` folder
183+
- Uses Mintlify (`.mdx` files)
184+
- Code blocks can auto-sync from SDK examples
185+
- Run `mint broken-links` to validate
186+
- Follow `openhands/DOC_STYLE_GUIDE.md`
187+
188+
### Blog (OpenHands/growth-utils)
189+
190+
- Posts in `blog-post/posts/YYYYMMDD-title.md`
191+
- Assets in `blog-post/assets/YYYYMMDD-title/`
192+
- Frontmatter format:
193+
```yaml
194+
---
195+
title: "Post Title"
196+
excerpt: "Brief description"
197+
coverImage: "/assets/blog/YYYYMMDD-title/cover.png"
198+
date: "YYYY-MM-DDTHH:MM:SS.000Z"
199+
authors:
200+
- name: Author Name
201+
picture: "/assets/blog/authors/author.png"
202+
ogImage:
203+
url: "/assets/blog/YYYYMMDD-title/cover.png"
204+
---
205+
```
206+
207+
## Example Feature Analysis
208+
209+
**Feature: Browser Session Recording (SDK v1.8.0)**
210+
211+
1. **SDK**: ✅ Implemented in `openhands.tools.browser`
212+
2. **CLI**: ❌ No replay/export commands
213+
3. **GUI**: ❌ No recording viewer component
214+
4. **Docs**: ✅ Guide at `sdk/guides/browser-session-recording.mdx`
215+
5. **Blog**: ❌ Could highlight for web scraping users
216+
6. **Video**: Consider 2-minute demo
217+
218+
**Recommendation**: Medium priority. Docs done, CLI/GUI low urgency (advanced feature), blog post optional.
219+
220+
## Quick Commands
221+
222+
```bash
223+
# Check SDK feature presence
224+
grep -r "feature_name" software-agent-sdk/openhands/ --include="*.py"
225+
226+
# Check CLI support
227+
grep -r "feature_name" OpenHands-CLI/openhands_cli/ --include="*.py"
228+
229+
# Check GUI support
230+
grep -r "featureName" OpenHands/frontend/src/ --include="*.ts" --include="*.tsx"
231+
232+
# Check docs coverage
233+
grep -r "feature" docs/sdk/ --include="*.mdx"
234+
235+
# Check blog mentions
236+
grep -r "feature" growth-utils/blog-post/posts/ --include="*.md"
237+
```
238+
239+
## Important Notes
240+
241+
- Always get user confirmation before creating issues or starting implementation
242+
- Consider feature maturity — new features may change before full rollout
243+
- Cross-reference PRs between repositories in issue descriptions
244+
- For breaking changes, coordinate release timing across all components

0 commit comments

Comments
 (0)