Skip to content

README.md

Latest commit

 

History

History
281 lines (219 loc) · 6.94 KB

README.md

File metadata and controls

281 lines (219 loc) · 6.94 KB

OpenSearch Feature Explorer

A tool to analyze OpenSearch release notes and generate detailed feature/release reports.

Overview

graph TB
    subgraph Input
        RN[Release Notes]
        PR[Pull Requests]
        Issue[Issues]
        Docs[Docs/Blogs]
    end
    subgraph "Kiro CLI + MCP"
        Agent[Agents]
        MCP[OpenSearch Docs MCP]
    end
    subgraph Output
        FR[Feature Reports]
        RR[Release Reports]
        GH[GitHub Issues]
    end
    RN --> Agent
    PR --> Agent
    Issue --> Agent
    Docs --> MCP --> Agent
    Agent --> FR
    Agent --> RR
    Agent --> GH
Loading

Agents

Agent Description
group-release Group raw items into feature groups → save to groups.json
review-groups Review and refine groups (split over-aggregated, merge related)
review-release Review release content
planner Create GitHub Project and Issues from groups.json
create-issues Create individual investigation Issues from tracking Issue
investigate Deep investigation (4 modes: Issue, PR, Feature, Interactive Q&A)
summarize Aggregate release reports into release summary
generate-release-docs Generate release docs from existing feature documents
refactor Batch structural changes to existing reports
translate Translate reports to other languages
dev Development and maintenance of this tool itself

Note: fetch-release runs as a Python function directly (not as a Kiro agent).

Requirements

  • Python 3.8+
  • Kiro CLI
  • GitHub CLI (gh) - authenticated via gh auth login
  • Node.js (for GitHub MCP Server)

GitHub Token Scopes

Run gh auth login with required scopes:

gh auth login -s read:org,repo,workflow,project
Scope Purpose
repo Issue/PR operations
project GitHub Projects (progress tracking)
workflow GitHub Actions (MkDocs deployment)
read:org Organization info
gist (included by default)

Naming Conventions

Resource Pattern Example
GitHub Project v{version} Investigation v3.0.0 Investigation
Issue (group) [{category}] {group_name} [feature] Star Tree Index
Label (release) release/v{version} release/v3.0.0
Label (status) status/{status} status/todo, status/done
Cache directory .cache/releases/v{version}/ .cache/releases/v3.0.0/
Data directory data/releases/v{version}/ data/releases/v3.0.0/
Release report docs/releases/v{version}/features/{repo}/{item-name}.md docs/releases/v3.0.0/features/opensearch/star-tree-index.md
Feature report docs/features/{repo}/{feature-name}.md docs/features/opensearch/star-tree-index.md

Setup

git clone https://github.com/tkykenmt/opensearch-feature-explorer.git
cd opensearch-feature-explorer
pip install -r requirements.txt

# Authenticate GitHub CLI (required for GitHub MCP)
gh auth login

GitHub Repository Settings

Enable the following in your repository settings (Settings → General):

  • Pull Requests: Enable "Automatically delete head branches" to clean up feature branches after PR merge
  • Pages (Settings → Pages): Set Source to "GitHub Actions" for automatic deployment

Usage

Use Case 1: Full Release Investigation

Complete workflow for investigating a new OpenSearch release.

flowchart TB
    A[release-investigate] --> B[(Release Reports)]
    A --> C[(Feature Reports)]
    A --> D[(Release Summary)]
Loading 
python run.py release-investigate 3.0.0
Manual step-by-step execution

Step 1: Fetch Release Notes

flowchart TB
    A[fetch-release] --> B[(raw-items.json)]
Loading 
python run.py fetch-release 3.0.0

Step 2: Group Items

flowchart TB
    A[(raw-items.json)] --> B[group-release]
    B --> C[(groups.json)]
Loading 
python run.py group-release 3.0.0 --all

Step 3: Create GitHub Project & Issues

flowchart TB
    A[(groups.json)] --> B[planner]
    B --> C[(GitHub Project)]
    B --> D[(Issues)]
Loading 
python run.py planner 3.0.0

Step 4: Investigate Each Issue

flowchart TB
    A[(Issue)] --> B[investigate]
    B --> C[(Release Report)]
    B --> D[(Feature Report)]
Loading 
python run.py investigate --issue 124
# Or batch process all
python run.py batch-investigate --all
# Or batch process specific version
python run.py batch-investigate 3.0.0 --all

Step 5: Create Release Summary

flowchart TB
    A[(Release Reports)] --> B[summarize]
    B --> C[(Release Summary)]
Loading 
python run.py summarize 3.0.0

Use Case 2: Single Feature Investigation

Quick investigation of a specific feature without full release workflow.

flowchart TB
    A[PR Number] --> B[investigate]
    C[Feature Name] --> B
    B --> D[Feature Report]
Loading 
# From a specific PR
python run.py investigate --pr 16233

# From feature name + PR
python run.py investigate --feature "Star Tree" --pr 16233

# Feature deep dive (searches all related PRs)
python run.py investigate --feature "Star Tree"

Use Case 3: Interactive Exploration

Explore features interactively with Q&A.

flowchart TB
    A[investigate] --> B[Q&A Session]
    B --> C[Import URLs]
    C --> B
Loading 
python run.py investigate

Planner Options

# Ignore existing tracking Issue and create new one
python run.py planner 3.0.0 -i
python run.py planner 3.0.0 --ignore-existing

Output Structure

docs/
├── features/                          # Cumulative feature documentation
│   ├── index.md
│   ├── opensearch/
│   │   ├── star-tree-index.md
│   │   └── star-tree-index.ja.md
│   ├── neural-search/
│   │   └── semantic-highlighting.md
│   └── k-nn/
│       └── explain-api.md
└── releases/
    └── v3.0.0/
        ├── index.md                   # Release index
        ├── summary.md                 # Release summary (from summarize)
        └── features/
            ├── opensearch/
            │   ├── star-tree-enhancements.md
            │   └── grpc-transport.md
            ├── neural-search/
            │   └── semantic-highlighting.md
            └── k-nn/
                └── explain-api.md

Local Preview

mkdocs serve
# Open http://localhost:8000

Development

See DEVELOPMENT.md for:

  • Project structure and conventions
  • Document templates and rules
  • Agent system details
  • Contributing guidelines

Disclosure

This project uses generative AI to create documentation. Generated content may contain inaccuracies. Always verify information against official OpenSearch documentation and source code.