# 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