Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
262 lines (192 loc) · 5.82 KB

CONTRIBUTING.md

File metadata and controls

262 lines (192 loc) · 5.82 KB

Contributing to Voice Vibe Coding

Thank you for your interest in contributing to Voice Vibe Coding! This document provides guidelines and instructions for contributing.

🌟 Ways to Contribute

1. Report Bugs

  • Use GitHub Issues to report bugs
  • Include detailed steps to reproduce
  • Provide error messages and logs
  • Specify your environment (OS, Python version, etc.)

2. Suggest Features

  • Open a GitHub Issue with the "enhancement" label
  • Describe the feature and its use case
  • Explain why it would be valuable

3. Improve Documentation

  • Fix typos and clarify instructions
  • Add examples and tutorials
  • Update outdated information
  • Translate documentation

4. Submit Code

  • Fix bugs
  • Implement new features
  • Optimize performance
  • Add tests

🚀 Development Setup

Quick Setup

# Clone the repository
git clone https://github.com/yourusername/voice-vibe-coding.git
cd voice-vibe-coding

# Run automated setup
./setup.sh

# Activate virtual environment
source venv/bin/activate

# Validate credentials
python scripts/validate_credentials.py

Development Workflow

  1. Create a branch for your changes:

    git checkout -b feature/your-feature-name

  2. Make your changes following code standards

  3. Test your changes thoroughly:

    # Run validation
python orchestrator.py --dry-run

# Test specific agents
python orchestrator.py --only your-agent-name

  4. Format code with Black:

    black .

  5. Commit your changes:

    git add .
git commit -m "feat: add new feature description"

📝 Code Standards

Python Code Style

  • Follow PEP 8 guidelines
  • Use Black for code formatting (black .)
  • Write clear, descriptive variable names
  • Add docstrings to functions and classes
  • Keep functions focused and small

Agent Prompt Guidelines

  • Use clear, directive language
  • Provide specific examples
  • Define expected inputs and outputs
  • Include error handling instructions
  • Document assumptions

Commit Message Format

Use conventional commits:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

git commit -m "feat(agents): add new content optimization agent"
git commit -m "fix(orchestrator): resolve concurrent client access error"
git commit -m "docs(readme): update ElevenLabs setup instructions"

🧪 Testing

Before Submitting

  1. Validate credentials:

    python scripts/validate_credentials.py

  2. Test with dry-run:

    python orchestrator.py --dry-run

  3. Run full pipeline with sample data:

    python orchestrator.py

  4. Check for errors in logs:

    tail -f logs/pipeline_*.log

Adding New Agents

When creating a new agent:

  1. Create agent file in .claude/agents/{agent-name}.md
  2. Follow existing agent structure
  3. Define clear inputs and expected outputs
  4. Add to AGENT_DESCRIPTIONS in orchestrator.py
  5. Test agent in isolation
  6. Document in README

📦 Pull Request Process

Before Submitting

  1. ✅ Code follows style guidelines
  2. ✅ All tests pass
  3. ✅ Documentation is updated
  4. ✅ Commit messages follow conventions
  5. ✅ No merge conflicts with main branch

Submitting PR

  1. Push your branch to GitHub:

    git push origin feature/your-feature-name

  2. Create Pull Request with:

    • Clear title describing the change
    • Detailed description of what and why
    • Reference related issues (Fixes #123)
    • Screenshots or examples if applicable

  3. Request review from maintainers

  4. Address feedback promptly

PR Review Criteria

  • Code quality and readability
  • Test coverage
  • Documentation completeness
  • Performance impact
  • Backward compatibility
  • Security considerations

🔍 Code Review Process

For Contributors

  • Be open to feedback and suggestions
  • Respond to review comments promptly
  • Make requested changes in additional commits
  • Don't take criticism personally - it's about the code

For Reviewers

  • Be respectful and constructive
  • Explain the reasoning behind suggestions
  • Focus on improving code quality
  • Approve when ready or request changes clearly

🐛 Debugging Tips

Common Issues

Agent not found:

  • Ensure agent file is in .claude/agents/
  • Check agent name matches exactly in orchestrator

Webhook not triggering:

  • Verify ngrok is running
  • Check webhook URL in ElevenLabs
  • Test with: curl http://localhost:5001/health

Pipeline hangs:

  • Check ANTHROPIC_API_KEY is NOT set in .env
  • Verify Claude CLI is authenticated: claude login
  • Review logs for stuck agents

Logging

Add detailed logging to help debug:

print(f"Debug: Variable value = {variable}")

Logs are stored in:

  • logs/pipeline_*.log - Pipeline execution
  • logs/webhook_server.log - Webhook events
  • orchestrator.log - Orchestrator output

📚 Resources

💬 Community

  • GitHub Discussions for questions
  • GitHub Issues for bugs and features
  • Be respectful and inclusive
  • Help others when you can

📄 License

By contributing, you agree that your contributions will be licensed under the same license as the project.

🙏 Thank You!

Every contribution, no matter how small, is valuable. Thank you for helping make Voice Vibe Coding better!

Questions? Open an issue or reach out to the maintainers.