ccs/CONTRIBUTING.md

CCS Contributing Guide

Welcome! We're excited you're interested in contributing to CCS. This guide will help you get started.

🚀 Quick Start for First-Time Contributors

Never contributed before? Start here:

1. Find a good first issue: Look for issues labeled good first issue
2. Read CLAUDE.md: Understand the project architecture and v3.0 features
3. Set up your environment: See Development Setup below
4. Make a small change: Fix a typo, improve docs, or tackle a small bug
5. Submit a PR: We'll guide you through the review process

Questions? Open a GitHub Discussion - we're here to help!

Development Guidelines

Philosophy

CCS follows these core principles:

• YAGNI: No features "just in case"
• KISS: Simple bash, no complexity
• DRY: One source of truth (config)

This tool does ONE thing well: enable instant switching between Claude accounts and alternative models.

Code Standards

Compatibility Requirements

• Unix: bash 3.2+ compatibility
• Windows: PowerShell 5.1+ compatibility
• Node.js: Node.js 14+ (for npm package)
• Dependencies: Only jq (Unix) or built-in PowerShell (Windows)

Code Style

Bash (Unix):

• Use #!/usr/bin/env bash shebang
• Quote variables: "$VAR" not $VAR
• Use [[ ]] for tests, not [ ]
• Follow existing indentation and naming patterns

PowerShell (Windows):

• Use CmdletBinding and proper parameter handling
• Follow PowerShell verb-noun convention
• Use proper error handling with try/catch
• Maintain compatibility with PowerShell 5.1+

Node.js (npm package):

• Use child_process.spawn for Claude CLI execution
• Handle SIGINT/SIGTERM for graceful shutdown
• Cross-platform path handling with path module
• ES modules preferred

Testing

Platform Testing

Test on all platforms before submitting PR:

• macOS (bash)
• Linux (bash)
• Windows (PowerShell, CMD, Git Bash)

Test Scenarios

1. Basic functionality:

   ccs            # Should use default profile
   ccs glm        # Should use GLM profile
   ccs kimi       # Should use Kimi profile
   ccs --version  # Should show version
   

2. v3.0 account-based profiles:

   ccs auth create work     # Should open Claude for login
   ccs work "test"          # Should use work profile
   # Run in different terminal concurrently:
   ccs personal "test"      # Should use personal profile
   

3. With arguments:

   ccs glm --help
   ccs /plan "test"
   

4. Error handling:

   ccs invalid-profile    # Should show error
   ccs --invalid-flag     # Should pass through to Claude
   

Submission Process

Before Submitting

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test on all platforms
5. Ensure existing tests pass

Pull Request Requirements

• Clear description of changes
• Testing instructions if applicable
• Link to relevant issues
• Follow existing commit message style

Commit Message Style

type(scope): description

[optional body]

[optional footer]

Examples:

fix(installer): handle git worktree detection
feat(config): support custom config location
docs(readme): update installation instructions

Development Setup

Local Development

# Clone your fork
git clone https://github.com/yourusername/ccs.git
cd ccs

# Create feature branch
git checkout -b your-feature-name

# Make changes
# Test locally with ./ccs

# Run tests
./tests/edge-cases.sh  # Unix
./tests/edge-cases.ps1 # Windows

Testing npm Package Locally

# Build and test npm package
npm pack                              # Creates @kaitranntt-ccs-X.Y.Z.tgz
npm install -g @kaitranntt-ccs-X.Y.Z.tgz  # Test installation
ccs --version                         # Verify it works
ccs glm "test"                        # Test functionality

# Cleanup
npm uninstall -g @kaitranntt/ccs
rm @kaitranntt-ccs-X.Y.Z.tgz
rm -rf ~/.ccs  # Clean test environment

Testing Installer

# Test Unix installer
./installers/install.sh

# Test Windows installer (in PowerShell)
.\installers\install.ps1

Areas for Contribution

Looking for where to start? Check GitHub Issues for:

• good first issue - Great for first-time contributors
• help wanted - We need your expertise!
• documentation - Improve our docs

Priority Areas

1. v3.0 Enhancements:

   • Profile management commands
   • Better instance isolation
   • Profile import/export

2. Enhanced error handling:

   • Better error messages
   • Recovery suggestions
   • Helpful Claude CLI detection

3. Documentation:

   • More usage examples
   • Integration guides
   • Video tutorials

4. Testing:

   • Expand test coverage
   • Add CI/CD tests
   • Performance benchmarks

Bug Fixes

• Installer issues on different platforms
• Edge cases in config parsing
• Windows-specific compatibility
• v3.0 concurrent session edge cases

Review Process

What to expect:

1. Automated checks (GitHub Actions):

   • Syntax validation
   • Basic functionality tests
   • npm package build test

2. Manual review (usually within 1-3 days):

   • Code quality and style
   • Platform compatibility
   • Philosophy alignment (YAGNI/KISS/DRY)

3. Testing (by maintainers):

   • Cross-platform verification (macOS, Linux, Windows)
   • Integration testing
   • v3.0 features validation

Tips for faster review:

• Keep PRs focused and small
• Include tests for new features
• Test on multiple platforms before submitting
• Link to related issues

Community

Getting Help

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions or share ideas
• README: Check README.md for usage examples

Communication Channels

• Primary: GitHub Issues
• Questions: GitHub Discussions
• Updates: Watch the repository for release notifications

Code of Conduct

Be respectful, constructive, and focused on the project's philosophy of simplicity and reliability.

We do not tolerate:

• Harassment or discrimination
• Spam or off-topic comments
• Disrespectful or unprofessional behavior

We encourage:

• Helpful feedback and constructive criticism
• Collaboration and knowledge sharing
• Patience with newcomers

📚 Additional Resources

• CLAUDE.md: Technical architecture and v3.0 implementation details
• README.md: User-facing documentation and examples
• GitHub Issues: Track bugs, features, and discussions
• VERSION: Current version number

🎯 Release Process

For maintainers:

1. Bump version: ./scripts/bump-version.sh [major|minor|patch]
2. Update CHANGELOG if applicable
3. Commit: git commit -m "chore: bump version to X.Y.Z"
4. Tag: git tag vX.Y.Z
5. Push: git push origin main && git push origin vX.Y.Z
6. GitHub Actions will automatically publish to npm

📄 License

By contributing to CCS, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to CCS!

Remember: Keep it simple, test thoroughly, and stay true to the YAGNI/KISS/DRY philosophy.