Add issue management and development workflow documentation
This commit is contained in:
371
ISSUES.md
Normal file
371
ISSUES.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user