switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity
This repository has been archived on 2026-04-03. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
92f4f87b6a46624c6143bae1f534012aa21d7c3c
core/ISSUES.md

8.1 KiB
Raw Blame History

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

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

## 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

## 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

## 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 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

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:

## 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 View Git Blame Copy Permalink