diff --git a/ISSUES.md b/ISSUES.md new file mode 100644 index 0000000..9e90d5b --- /dev/null +++ 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