Add issue management and development workflow documentation

2026-02-03 23:26:19 +00:00
parent 51b0586160
commit 477c61f8ec
1 changed files with 371 additions and 0 deletions
--- a/ISSUES.md
+++ b/ISSUES.md
@@ -0,0 +1,371 @@
+# Issue Management & Development Workflow
+
+This document outlines the development workflow, issue labeling system, and contribution process for Chat Switchboard.
+
+## 📋 Issue Lifecycle
+
+```
+Idea → Issue → Branch → Development → PR → Review → Merge → Close
+```
+
+### 1. **Create Issue**
+- Use descriptive title with prefix: `[CATEGORY] Description`
+- Categories: `BACKEND`, `FRONTEND`, `EXTENSIONS`, `DATABASE`, `DEVOPS`, `TESTING`, `DOCS`, `FEATURE`
+- Fill in description template
+- Add priority emoji in body
+- List dependencies (reference issue numbers)
+- Estimate time
+
+### 2. **Create Branch**
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b issue-XX-short-description
+```
+
+Branch naming: `issue-XX-short-kebab-case-description`
+
+### 3. **Development**
+- Keep commits focused and atomic
+- Reference issue in commits: `Fix #XX: Description`
+- Update issue with progress comments
+- Request help if blocked
+
+### 4. **Create Pull Request**
+- **Base:** `develop` (NOT `main`)
+- **Title:** `[CATEGORY] Description (closes #XX)`
+- Use PR template checklist
+- Link to issue with `Closes #XX`
+- Add screenshots/demos if UI changes
+
+### 5. **Code Review**
+- At least 1 approval required
+- All CI checks must pass
+- Address review comments
+- Squash commits if messy
+
+### 6. **Merge**
+- Squash and merge to `develop`
+- Delete branch after merge
+- Issue auto-closes
+
+### 7. **Release**
+- Periodically merge `develop` → `main`
+- Tag with semantic version
+- Auto-deploy to production
+
+---
+
+## 🏷️ Labeling System
+
+### Priority (Use Emoji in Body)
+- 🔴🔴🔴 **CRITICAL** - Blocker, must do first
+- 🔴🔴 **HIGH** - Important, do soon
+- 🔴 **MEDIUM** - Normal priority
+- 🟡 **LOW** - Nice to have
+- ⚪ **BACKLOG** - Maybe someday
+
+### Category (Use Prefix in Title)
+- `[BACKEND]` - Go server, API, database
+- `[FRONTEND]` - JavaScript UI, HTML/CSS
+- `[EXTENSIONS]` - Plugin development
+- `[DATABASE]` - Schema, migrations, queries
+- `[DEVOPS]` - Docker, CI/CD, deployment
+- `[TESTING]` - Tests, QA
+- `[DOCS]` - Documentation
+- `[FEATURE]` - New feature request
+- `[BUG]` - Something broken
+- `[INFRASTRUCTURE]` - Project setup, tooling
+
+### Special Tags (Add to Body)
+- `🌟 killer-feature` - Unique differentiator
+- `🔧 breaking-change` - API/schema breaking
+- `🚀 performance` - Performance optimization
+- `🔒 security` - Security-related
+- `♿ accessibility` - A11y improvements
+- `🎨 ui/ux` - Design/UX improvements
+
+---
+
+## 📝 Issue Templates
+
+### Bug Report
+```markdown
+## Description
+Clear description of the bug.
+
+## Steps to Reproduce
+1. Go to...
+2. Click on...
+3. See error
+
+## Expected Behavior
+What should happen.
+
+## Actual Behavior
+What actually happens.
+
+## Environment
+- OS: [e.g., Ubuntu 22.04]
+- Browser: [e.g., Chrome 120]
+- Version: [e.g., v0.2.0]
+
+## Screenshots
+If applicable.
+
+## Priority
+🔴🔴 **HIGH** - Blocks users
+```
+
+### Feature Request
+```markdown
+## Description
+Clear description of the feature.
+
+## Problem It Solves
+What user pain point does this address?
+
+## Proposed Solution
+How should it work?
+
+## Alternatives Considered
+Other approaches you thought about.
+
+## Priority
+🟡 **LOW** - Nice to have
+
+## Estimated Time
+X hours
+```
+
+### Extension Submission
+```markdown
+## Extension Name
+`extension-name`
+
+## Description
+What does this extension do?
+
+## Type
+- [ ] Frontend (UI)
+- [ ] Backend (Tool/API)
+- [ ] Hybrid
+
+## Tools/Features
+List of tools/hooks this provides.
+
+## Installation
+How to install and configure.
+
+## Dependencies
+- Requires: Issue #XX
+- Python packages: `requests`, `beautifulsoup4`
+
+## Checklist
+- [ ] Follows extension spec (`docs/PLUGIN_SPEC.md`)
+- [ ] Includes `extension.json` manifest
+- [ ] Has README with examples
+- [ ] Includes tests
+- [ ] Security reviewed (no arbitrary code execution)
+```
+
+---
+
+## 🔄 Development Workflow
+
+### Daily Development
+1. **Pick an issue** from the board
+2. **Self-assign** the issue
+3. **Create branch** from `develop`
+4. **Code** and commit frequently
+5. **Push** and open PR when ready
+6. **Request review** from maintainers
+7. **Merge** once approved
+
+### CI/CD Pipeline
+```
+Push → Lint → Test → Build → Deploy (if main)
+```
+
+All PRs must pass:
+- ✅ Go tests
+- ✅ Go lint (golangci-lint)
+- ✅ Frontend lint (ESLint)
+- ✅ Build standalone HTML
+- ✅ Docker build
+
+### Release Process
+1. **Develop branch** accumulates features
+2. **Create release branch** `release/vX.Y.Z`
+3. **Test thoroughly**
+4. **Merge to main** with tag
+5. **CI auto-deploys** to production
+6. **Merge back to develop**
+
+---
+
+## 🎯 Current Priorities
+
+See [ROADMAP.md](ROADMAP.md) for phases.
+
+### Phase 1 (MVP Backend)
+- Issue #2: Backend init
+- Issue #3: Database
+- Issue #4: Auth
+- Issue #6: Extension Manager
+
+### Phase 2 (Core Features)
+- Issue #8: Chat Engine
+- Issue #12: Workflow Engine
+- Issue #10: Mode Switching
+
+### Phase 3 (Killer Features)
+- Issue #13: Workflow UI
+- Issue #11: Extension UI
+
+---
+
+## 🤝 Contribution Guidelines
+
+### Before Starting Work
+1. **Check existing issues** - don't duplicate
+2. **Comment on issue** - let others know you're working on it
+3. **Ask questions** - if anything is unclear
+
+### Code Style
+- **Go:** `gofmt`, follow standard Go conventions
+- **JavaScript:** ESLint config, 2-space indent
+- **Python:** Black formatter, PEP 8
+
+### Commit Messages
+```
+[Category] Short description (50 chars)
+
+Longer description if needed. Explain WHY, not WHAT.
+
+Closes #XX
+```
+
+Good examples:
+- `[Backend] Add JWT refresh token rotation (closes #4)`
+- `[Frontend] Implement WebSocket reconnection logic (closes #10)`
+- `[Extensions] Create web-search plugin (closes #7)`
+
+### Testing Requirements
+- **Backend:** Unit tests for new handlers/functions
+- **Extensions:** Integration tests for tools
+- **Frontend:** E2E tests for critical flows
+
+### Documentation
+- Update README if adding user-facing features
+- Update API docs if changing endpoints
+- Add inline comments for complex logic
+- Update ROADMAP if scope changes
+
+---
+
+## 🐛 Bug Triage
+
+### Severity Levels
+1. **Critical:** Production down, data loss, security breach
+2. **High:** Major feature broken, affects many users
+3. **Medium:** Minor feature broken, affects some users
+4. **Low:** Cosmetic, edge case, rare occurrence
+
+### Response Times
+- Critical: Fix immediately
+- High: Fix within 1 week
+- Medium: Fix within 1 month
+- Low: Backlog
+
+---
+
+## 📊 Project Board
+
+### Columns
+1. **Backlog** - Not yet prioritized
+2. **Ready** - Prioritized, ready to start
+3. **In Progress** - Actively being worked on
+4. **Review** - PR open, awaiting review
+5. **Done** - Merged and closed
+
+### Moving Cards
+- Assign yourself when moving to "In Progress"
+- Link PR when moving to "Review"
+- Close issue when merged
+
+---
+
+## 🔍 Finding Issues to Work On
+
+### Good First Issues
+- Labeled with 🟡 **LOW** priority
+- Clear description and acceptance criteria
+- No complex dependencies
+
+### Help Wanted
+- Blocked issues needing expertise
+- Complex problems needing collaboration
+
+### Current Sprint
+- See project board "Ready" column
+- Check ROADMAP.md for phase priorities
+
+---
+
+## 📞 Getting Help
+
+- **Questions:** Comment on the issue
+- **Blocked:** Tag maintainers in comment
+- **Design decisions:** Open discussion issue
+- **Security:** Email privately (don't open public issue)
+
+---
+
+## 🎓 Learning Resources
+
+### Go
+- [Effective Go](https://go.dev/doc/effective_go)
+- [Go by Example](https://gobyexample.com/)
+
+### Extensions
+- `docs/PLUGIN_SPEC.md` - Complete spec
+- `extensions/_template-python/` - Starter template
+- `docs/GETTING_STARTED.md` - Setup guide
+
+### Architecture
+- `docs/ARCHITECTURE.md` - System design
+- `docs/WORKFLOWS.md` - Workflow system
+- `migrations/002_full_schema.sql` - Database schema
+
+---
+
+## ✅ PR Checklist
+
+Copy this into PR description:
+
+```markdown
+## Checklist
+- [ ] Code follows style guide
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented in CHANGELOG)
+- [ ] All CI checks pass
+- [ ] Manually tested
+- [ ] Screenshots/demo included (if UI changes)
+- [ ] Closes #XX
+```
+
+---
+
+## 🎉 Recognition
+
+Contributors will be:
+- Listed in CONTRIBUTORS.md
+- Mentioned in release notes
+- Given credit in extension marketplace (if applicable)
+
+---
+
+**Last Updated:** 2026-02-03  
+**Maintained By:** @xcaliber