@openhands/extensions 0.0.1-alpha → 0.2.0

package/plugins/release-notes/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "release-notes",
+  "version": "1.0.0",
+  "description": "Generate consistent, well-structured release notes from git history with categorized changelog, contributor attribution, and semver tag support.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "release-notes",
+    "changelog",
+    "git",
+    "semver",
+    "versioning"
+  ]
+}

package/plugins/release-notes/README.md

@@ -0,0 +1,283 @@
+# Release Notes Generator Plugin
+
+Automated release notes generation using OpenHands agents. This plugin provides GitHub workflows that generate consistent, well-structured release notes when release tags are pushed.
+
+## Quick Start
+
+Copy the workflow file to your repository:
+
+```bash
+mkdir -p .github/workflows
+curl -o .github/workflows/release-notes.yml \
+  https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/release-notes/workflows/release-notes.yml
+```
+
+Then configure the required secrets (see [Installation](#installation) below).
+
+## Features
+
+- **Automatic Tag Detection**: Automatically finds the previous release tag to determine the commit range
+- **Agent-Based Summaries**: Uses an OpenHands agent to judge significance, merge related PRs, and decide what is worth mentioning
+- **Structured GitHub Context**: Feeds the agent merged PR titles, labels, bodies, authors, and contributor information for the release range
+- **Conventional Commits Support**: Uses commit prefixes (`feat:`, `fix:`, `docs:`, etc.) as categorization hints for the agent
+- **PR Label Support**: Uses GitHub PR labels as additional hints for the agent
+- **Contributor Attribution**: Includes PR numbers and author usernames for each change the agent keeps
+- **Attribution Validation**: Fails the workflow if any release-range PR/commit or corresponding author is omitted from the final notes
+- **Deterministic Coverage Appendix**: When the agent omits lower-signal PRs, the action appends a compact `### 🔎 Small Fixes/Internal Changes` appendix grouped by author so every PR and author in the release range is still listed somewhere in the output
+- **New Contributor Highlighting**: Identifies first-time human contributors from merged PR history and excludes bot accounts
+- **Flexible Output**: Updates GitHub release notes directly or outputs for CHANGELOG.md
+
+## Plugin Contents
+
+```
+plugins/release-notes/
+├── README.md              # This file
+├── SKILL.md               # Plugin definition
+├── action.yml             # Composite GitHub Action
+├── scripts/               # Python scripts
+│   ├── agent_script.py    # OpenHands agent orchestration
+│   ├── generate_release_notes.py
+│   ├── prompt.py
+│   └── validate_release_notes.py
+└── workflows/             # Example GitHub workflow files
+    └── release-notes.yml
+```
+
+## Installation
+
+### 1. Copy the Workflow File
+
+Copy the workflow file to your repository's `.github/workflows/` directory:
+
+```bash
+mkdir -p .github/workflows
+curl -o .github/workflows/release-notes.yml \
+  https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/release-notes/workflows/release-notes.yml
+```
+
+### 2. Configure Secrets
+
+Add the following secrets in your repository settings (**Settings → Secrets and variables → Actions**):
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `LLM_API_KEY` | Yes | API key for the LLM used by the OpenHands agent |
+| `GITHUB_TOKEN` | Auto | Provided automatically by GitHub Actions |
+
+**Note**: The default `GITHUB_TOKEN` is sufficient for most use cases. For repositories that need elevated permissions, use a personal access token.
+
+### 3. Customize the Workflow (Optional)
+
+Edit the workflow file to customize:
+
+```yaml
+- name: Generate Release Notes
+  uses: OpenHands/extensions/plugins/release-notes@main
+  with:
+    # The release tag to generate notes for
+    tag: ${{ github.ref_name }}
+
+    # Optional: Override previous tag detection
+    # previous-tag: v1.0.0
+
+    # Include internal/infrastructure changes (default: false)
+    include-internal: false
+
+    # Output format: 'release' (GitHub release) or 'changelog' (CHANGELOG.md)
+    output-format: release
+
+    # Optional model override
+    # llm-model: anthropic/claude-sonnet-4-5-20250929
+
+    # Secrets
+    llm-api-key: ${{ secrets.LLM_API_KEY }}
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Usage
+
+### Automatic Triggers
+
+Release notes are automatically generated when:
+
+1. A tag matching `v[0-9]+.[0-9]+.[0-9]+*` is pushed (e.g., `v1.2.0`, `v2.0.0-beta.1`)
+
+### Manual Triggering
+
+You can also manually trigger release notes generation:
+
+1. Go to **Actions** in your repository
+2. Select the "Generate Release Notes" workflow
+3. Click **Run workflow**
+4. Enter the tag to generate notes for
+
+## Action Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `tag` | Yes | - | The release tag to generate notes for |
+| `previous-tag` | No | Auto-detect | Override automatic detection of previous release |
+| `include-internal` | No | `false` | Include internal/infrastructure changes |
+| `output-format` | No | `release` | Output format: `release` or `changelog` |
+| `llm-model` | No | `anthropic/claude-sonnet-4-5-20250929` | LLM used by the OpenHands agent |
+| `llm-base-url` | No | - | Optional custom LLM endpoint |
+| `llm-api-key` | Yes | - | API key for the OpenHands agent's LLM |
+| `github-token` | Yes | - | GitHub token for API access |
+
+## Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `release-notes` | The generated release notes in markdown format |
+| `previous-tag` | The detected or provided previous release tag |
+| `commit-count` | Number of commits included in the release |
+| `contributor-count` | Number of unique contributors |
+| `new-contributor-count` | Number of first-time contributors |
+
+## Release Notes Structure
+
+Generated release notes follow this format:
+
+```markdown
+## [v1.2.0] - 2026-03-06
+
+### ⚠️ Breaking Changes
+- Remove deprecated `--legacy` CLI flag (#456) @maintainer
+
+### ✨ New Features
+- Add support for Claude Sonnet 4.6 model (#445) @contributor1
+- Implement parallel tool execution (#438) @contributor2
+
+### 🐛 Bug Fixes
+- Fix WebSocket reconnection on network interruption (#451) @contributor3
+- Resolve memory leak in long-running sessions (#447) @maintainer
+
+### 📚 Documentation
+- Update installation guide for v1.2 (#442) @contributor2
+
+### 🏗️ Internal/Infrastructure
+- Upgrade CI to use Node 20 (#440) @maintainer
+
+### 👥 New Contributors
+- @contributor3 made their first contribution in #451
+
+**Full Changelog**: https://github.com/org/repo/compare/v1.1.0...v1.2.0
+```
+
+## Change Categorization
+
+The agent receives deterministic categorization hints, but it makes the final decision about significance, grouping, and which entries to keep.
+
+### 1. Conventional Commit Prefixes
+
+| Prefix | Category |
+|--------|----------|
+| `BREAKING:` or `!:` suffix | ⚠️ Breaking Changes |
+| `feat:`, `feature:` | ✨ New Features |
+| `fix:`, `bugfix:` | 🐛 Bug Fixes |
+| `docs:` | 📚 Documentation |
+| `chore:`, `ci:`, `refactor:`, `test:`, `build:` | 🏗️ Internal/Infrastructure |
+
+### 2. PR Labels
+
+| Labels | Category |
+|--------|----------|
+| `breaking-change`, `breaking` | ⚠️ Breaking Changes |
+| `enhancement`, `feature` | ✨ New Features |
+| `bug`, `bugfix` | 🐛 Bug Fixes |
+| `documentation`, `docs` | 📚 Documentation |
+| `internal`, `chore`, `ci`, `dependencies` | 🏗️ Internal/Infrastructure |
+
+## Content Guidelines
+
+The generator follows these principles:
+
+- **Conversational overview**: Starts with a short plain-language summary of the release before the detailed sections
+- **Concise but informative**: The agent decides which changes matter and can merge related PRs into a single higher-signal bullet
+- **User-focused**: The agent prioritizes end-user and client-developer impact over low-level implementation detail
+- **Internal changes stay secondary**: CI churn, prompt tweaks, workflow plumbing, contributor ergonomics, and similar toolkit-maintainer details belong in `### 🔎 Small Fixes/Internal Changes` unless they are unusually significant
+- **Scannable**: Easy to quickly find relevant changes
+- **Imperative mood**: Uses "Add feature" not "Added feature"
+- **Attribution**: Includes PR number and author for traceability
+
+## Validation Guardrail
+
+After the agent writes `release_notes.md`, the action runs `scripts/validate_release_notes.py`.
+That validator rebuilds the deterministic PR/author context for the same tag range and checks that the final notes:
+
+- include at least one explicit PR or commit reference in every user-facing change bullet
+- include the author handle for every referenced PR or commit
+- do not reference unknown PRs or commits
+- cover every PR/commit in the release range somewhere in the markdown
+
+If the agent keeps the main sections concise and omits lower-signal PRs, `agent_script.py` inserts a compact `### 🔎 Small Fixes/Internal Changes` appendix before the full changelog link. That appendix is grouped by author so the output remains readable while still being exhaustive.
+
+## Customizing Output
+
+### Excluding Internal Changes
+
+By default, internal/infrastructure changes are excluded. To include them:
+
+```yaml
+- uses: OpenHands/extensions/plugins/release-notes@main
+  with:
+    include-internal: true
+```
+
+### Generating CHANGELOG.md Entries
+
+To generate output suitable for a CHANGELOG.md file:
+
+```yaml
+- uses: OpenHands/extensions/plugins/release-notes@main
+  with:
+    output-format: changelog
+```
+
+Then use the output in a subsequent step:
+
+```yaml
+- name: Update CHANGELOG
+  run: |
+    echo "${{ steps.release-notes.outputs.release-notes }}" >> CHANGELOG.md
+```
+
+## Troubleshooting
+
+### Missing LLM Credentials
+
+Make sure `LLM_API_KEY` is configured in repository secrets and passed to the action.
+
+### Release Notes Not Generated
+
+1. Check that the tag matches the semver pattern: `v[0-9]+.[0-9]+.[0-9]+*`
+2. Verify the workflow file is in `.github/workflows/`
+3. Check the Actions tab for error messages
+
+### Wrong Previous Tag Detected
+
+Use the `previous-tag` input to override automatic detection:
+
+```yaml
+previous-tag: v1.0.0
+```
+
+### Missing Contributors
+
+The generator uses the GitHub API to fetch PR authors. Ensure:
+1. Commits are associated with merged PRs
+2. The `GITHUB_TOKEN` has read access to pull requests
+
+## Security
+
+- Uses the default `GITHUB_TOKEN` for API access
+- No secrets are persisted or logged
+- Read-only access to repository history and PRs
+
+## Contributing
+
+See the main [extensions repository](https://github.com/OpenHands/extensions) for contribution guidelines.
+
+## License
+
+This plugin is part of the OpenHands extensions repository. See [LICENSE](../../LICENSE) for details.

package/plugins/release-notes/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: release-notes
+description: Generate consistent, well-structured release notes from git history. Triggered on release tags following semver patterns (v*.*.*) to produce categorized changelog with breaking changes, features, fixes, and contributor attribution.
+triggers:
+- /release-notes
+---
+
+# Release Notes Generator Plugin
+
+Automates the generation of standardized release notes for OpenHands repositories using an OpenHands agent. The agent reviews the release range, judges significance, groups related PRs, and produces concise markdown for GitHub releases or changelogs.
+
+## Features
+
+- **Automatic tag detection**: Finds the previous release tag to determine the commit range
+- **Agent-based editing**: Lets the agent decide which changes matter, open with a short conversational summary, and group related PRs into higher-signal summaries while keeping toolkit-maintainer-only details out of the main sections unless they are unusually significant
+- **Structured GitHub context**: Supplies PR titles, labels, descriptions, and contributor metadata to guide the agent
+- **Contributor attribution**: Includes PR numbers and author usernames for each change
+- **Attribution validation**: Verifies every change bullet contains explicit PR/commit references and the matching author handles
+- **Full coverage appendix**: Appends a compact `### 🔎 Small Fixes/Internal Changes` section grouped by author when needed so every PR and author in the release range is still listed somewhere in the final markdown
+- **New contributor highlighting**: Identifies first-time human contributors from merged PR history and excludes bot accounts
+- **Flexible output**: Can update GitHub release notes or generate CHANGELOG.md entries
+
+## Quick Start
+
+### As a GitHub Action
+
+Copy the workflow file to your repository:
+
+```bash
+mkdir -p .github/workflows
+curl -o .github/workflows/release-notes.yml \
+  https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/release-notes/workflows/release-notes.yml
+```
+
+Configure required secrets (see the README for details).
+
+### Manual Invocation
+
+Use the `/release-notes` trigger in an OpenHands conversation to generate release notes for the current repository.
+
+## Release Notes Format
+
+Generated release notes follow this structure:
+
+```markdown
+## [v1.2.0] - 2026-03-06
+
+### ⚠️ Breaking Changes
+- Remove deprecated `--legacy` CLI flag (#456) @maintainer
+
+### ✨ New Features
+- Add support for Claude Sonnet 4.6 model (#445) @contributor1
+
+### 🐛 Bug Fixes
+- Fix WebSocket reconnection on network interruption (#451) @contributor3
+
+### 📚 Documentation
+- Update installation guide (#442) @contributor2
+
+### 👥 New Contributors
+- @contributor3 made their first contribution in #451
+
+**Full Changelog**: https://github.com/org/repo/compare/v1.1.0...v1.2.0
+```
+
+## Change Categorization
+
+Changes are categorized based on:
+
+1. **Conventional commit prefixes**: `feat:`, `fix:`, `docs:`, `chore:`, `BREAKING:`
+2. **PR labels**: `breaking-change`, `bug`, `enhancement`, `documentation`
+
+| Category | Commit Prefixes | PR Labels |
+|----------|-----------------|-----------|
+| Breaking Changes | `BREAKING:`, `!:` suffix | `breaking-change`, `breaking` |
+| Features | `feat:`, `feature:` | `enhancement`, `feature` |
+| Bug Fixes | `fix:`, `bugfix:` | `bug`, `bugfix` |
+| Documentation | `docs:` | `documentation`, `docs` |
+| Internal | `chore:`, `ci:`, `refactor:`, `test:` | `internal`, `chore`, `ci` |
+
+## Configuration
+
+See the [README](./README.md) for full configuration options and workflow setup instructions.

package/plugins/release-notes/action.yml

@@ -0,0 +1,117 @@
+---
+name: OpenHands Release Notes Generator
+description: Generate agent-authored release notes from git history and PR context
+author: OpenHands
+
+branding:
+    icon: file-text
+    color: green
+
+inputs:
+    tag:
+        description: The release tag to generate notes for
+        required: true
+    previous-tag:
+        description: Override automatic detection of previous release tag
+        required: false
+        default: ''
+    include-internal:
+        description: Include internal/infrastructure changes in the release notes
+        required: false
+        default: 'false'
+    output-format:
+        description: "Output format: 'release' (GitHub release) or 'changelog' (CHANGELOG.md)"
+        required: false
+        default: release
+    llm-model:
+        description: LLM model to use for agent-based release note generation
+        required: false
+        default: anthropic/claude-sonnet-4-5-20250929
+    llm-base-url:
+        description: LLM base URL (optional, for custom LLM endpoints)
+        required: false
+        default: ''
+    llm-api-key:
+        description: LLM API key (required)
+        required: true
+    github-token:
+        description: GitHub token for API access (required)
+        required: true
+
+outputs:
+    release-notes:
+        description: The generated release notes in markdown format
+        value: ${{ steps.generate.outputs.release_notes }}
+    previous-tag:
+        description: The detected or provided previous release tag
+        value: ${{ steps.generate.outputs.previous_tag }}
+    commit-count:
+        description: Number of commits included in the release
+        value: ${{ steps.generate.outputs.commit_count }}
+    contributor-count:
+        description: Number of unique contributors
+        value: ${{ steps.generate.outputs.contributor_count }}
+    new-contributor-count:
+        description: Number of first-time contributors
+        value: ${{ steps.generate.outputs.new_contributor_count }}
+
+runs:
+    using: composite
+    steps:
+        - name: Checkout extensions repository
+          uses: actions/checkout@v4
+          with:
+              repository: OpenHands/extensions
+              ref: main
+              path: extensions
+              sparse-checkout: plugins/release-notes
+
+        - name: Set up Python
+          uses: actions/setup-python@v5
+          with:
+              python-version: '3.12'
+
+        - name: Install uv
+          uses: astral-sh/setup-uv@v6
+          with:
+              enable-cache: true
+
+        - name: Generate release notes
+          id: generate
+          shell: bash
+          env:
+              LLM_MODEL: ${{ inputs.llm-model }}
+              LLM_BASE_URL: ${{ inputs.llm-base-url }}
+              LLM_API_KEY: ${{ inputs.llm-api-key }}
+              GITHUB_TOKEN: ${{ inputs.github-token }}
+              TAG: ${{ inputs.tag }}
+              PREVIOUS_TAG: ${{ inputs.previous-tag }}
+              INCLUDE_INTERNAL: ${{ inputs.include-internal }}
+              OUTPUT_FORMAT: ${{ inputs.output-format }}
+              REPO_NAME: ${{ github.repository }}
+          run: |
+              uv run --with openhands-sdk --with openhands-tools \
+                python extensions/plugins/release-notes/scripts/agent_script.py
+
+        - name: Validate PR and author attribution
+          shell: bash
+          env:
+              GITHUB_TOKEN: ${{ inputs.github-token }}
+              TAG: ${{ inputs.tag }}
+              PREVIOUS_TAG: ${{ inputs.previous-tag }}
+              INCLUDE_INTERNAL: ${{ inputs.include-internal }}
+              REPO_NAME: ${{ github.repository }}
+          run: |
+              python extensions/plugins/release-notes/scripts/validate_release_notes.py
+
+        - name: Update GitHub release (if release format)
+          if: inputs.output-format == 'release'
+          shell: bash
+          env:
+              GITHUB_TOKEN: ${{ inputs.github-token }}
+          run: |
+              if [ -f release_notes.md ]; then
+                echo "Updating release notes for tag ${{ inputs.tag }}"
+                gh release edit "${{ inputs.tag }}" --notes-file release_notes.md || \
+                  echo "Note: Could not update release. Release may not exist yet."
+              fi

package/plugins/release-notes/commands/release-notes.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Generate consistent, well-structured release notes from git history. Triggered on release tags following semver patterns (v*.*.*) to produce categorized changelog with breaking changes, features, fixes, and contributor attribution.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS