zilliztech--claude-context/packages/chrome-extension/CONTRIBUTING.md

Contributing to Chrome Extension

Thanks for your interest in contributing to the Claude Context Chrome extension!

📖 First time contributing? Please read the main contributing guide first for general setup and workflow.

Chrome Extension Development

This guide covers development specific to the Chrome extension.

Quick Commands

# Build Chrome extension
pnpm build:chrome

# Watch mode for development
pnpm dev:chrome

# Clean build artifacts
pnpm clean

# Lint code
pnpm lint

# Type checking
pnpm typecheck

# Generate icons
pnpm prebuild

Development Setup

1. Install Dependencies:

   cd packages/chrome-extension
   pnpm install
   

2. Build Extension:

   pnpm build
   

3. Load in Chrome:

   • Open Chrome and go to chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked" and select the dist folder

4. Development Mode:

   pnpm dev  # Watch mode for automatic rebuilds
   

Making Changes

1. Create a new branch for your feature/fix
2. Make changes in the src/ directory
3. Test in Chrome with "Reload extension" after changes
4. Follow commit guidelines in the main guide

Project Structure

src/
├── content.ts              # Content script for GitHub integration
├── background.ts           # Background service worker
├── options.ts             # Options/settings page
├── options.html           # Options page HTML
├── styles.css             # Extension styles
├── manifest.json          # Extension manifest
├── config/
│   └── milvusConfig.ts    # Milvus configuration
├── milvus/
│   └── chromeMilvusAdapter.ts  # Browser Milvus adapter
├── storage/
│   └── indexedRepoManager.ts   # Repository management
├── stubs/                 # Browser compatibility stubs
└── icons/                 # Extension icons

Development Workflow

1. Content Script Development

• Modify src/content.ts for GitHub UI integration
• Test on various GitHub repository pages
• Ensure UI doesn't conflict with GitHub's interface

2. Background Service Worker

• Edit src/background.ts for extension lifecycle management
• Handle cross-tab communication and data persistence
• Test extension startup and shutdown scenarios

3. Options Page

• Update src/options.ts and src/options.html for settings
• Test configuration persistence and validation
• Ensure user-friendly error messages

4. Testing Workflow

1. Make changes to source files
2. Run pnpm build or use pnpm dev for watch mode
3. Go to chrome://extensions/ and click "Reload" on the extension
4. Test functionality on GitHub repositories
5. Check Chrome DevTools console for errors

Browser Compatibility

WebPack Configuration

• webpack.config.js handles Node.js polyfills for browser environment
• Modules like crypto, fs, path are replaced with browser-compatible versions

Key Polyfills

• crypto-browserify - Cryptographic functions
• buffer - Node.js Buffer API
• process - Process environment variables
• path-browserify - Path manipulation
• vm-browserify - Virtual machine context

Testing Browser Compatibility

# Build and test in different browsers
pnpm build
# Load extension in Chrome, Edge, Brave, etc.

Extension-Specific Guidelines

Manifest V3 Compliance

• Use service workers instead of background pages
• Follow content security policy restrictions
• Handle permissions properly

Performance Considerations

• Minimize content script impact on GitHub page load
• Use efficient DOM manipulation
• Lazy load heavy components

Security Best Practices

• Validate all user inputs
• Sanitize HTML content
• Use secure communication between scripts
• Handle API keys securely

UI/UX Guidelines

• Match GitHub's design language
• Provide loading states for async operations
• Show clear error messages
• Ensure accessibility compliance

Chrome Extension Features

Core Functionality

• Repository Indexing: Parse GitHub repositories and create vector embeddings
• Semantic Search: Natural language code search within repositories
• UI Integration: Seamless GitHub interface enhancement
• Configuration Management: User settings and API key management

Advanced Features

• Cross-Repository Search: Search across multiple indexed repositories
• Context-Aware Search: Search similar code from selected snippets
• Progress Tracking: Real-time indexing progress indicators
• Offline Support: Local caching of indexed repositories

Testing Checklist

Manual Testing

• Extension loads without errors
• UI appears correctly on GitHub repository pages
• Indexing works for public repositories
• Search returns relevant results
• Options page saves configuration correctly
• Extension works across different GitHub page types
• No conflicts with GitHub's native functionality

Cross-Browser Testing

• Chrome (latest)
• Edge (Chromium-based)
• Brave Browser
• Other Chromium-based browsers

GitHub Integration Testing

• Repository home pages
• File browser pages
• Code view pages
• Pull request pages
• Different repository sizes
• Private repositories (with token)

Debugging

Chrome DevTools

1. Right-click extension icon → "Inspect popup"
2. Go to GitHub page → F12 → check console for content script errors
3. chrome://extensions/ → click "service worker" link for background script debugging

Common Issues

• Permission errors: Check manifest.json permissions
• CSP violations: Verify content security policy compliance
• Module not found: Check webpack polyfill configuration
• API errors: Validate API keys and network connectivity

Debug Commands

# Check build output (Unix/macOS)
ls -la dist/

# Check build output (Windows PowerShell)
Get-ChildItem dist/ | Format-Table -AutoSize

# Validate manifest (Unix/macOS)
cat dist/manifest.json | jq

# Validate manifest (Windows PowerShell)
Get-Content dist/manifest.json | ConvertFrom-Json | ConvertTo-Json -Depth 10

# Check for TypeScript errors (cross-platform)
pnpm typecheck

Publishing Preparation

Pre-Publishing Checklist

• All tests pass
• No console errors
• Icons generated correctly
• Manifest version updated
• README updated with new features
• Screenshots prepared for store listing

Build for Production

# Clean build
pnpm clean
pnpm build

# Verify bundle size (Unix/macOS)
ls -lh dist/

# Verify bundle size (Windows PowerShell)
Get-ChildItem dist/ | Select-Object Name, @{Name="Size";Expression={[math]::Round($_.Length/1KB,2)}} | Format-Table -AutoSize

Note

: Only maintainers can publish to Chrome Web Store

Questions?

• General questions: See main contributing guide
• Chrome extension specific issues: Open an issue with the chrome-extension label
• Browser compatibility: Test across different Chromium browsers
• GitHub integration: Ensure changes work across all GitHub page types