tiennm99/ccs
1
0
Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-07-16 02:11:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(contributing): refresh contributor workflow

Browse Source
This commit is contained in:
Tam Nhu Tran
2026-03-17 15:29:36 -04:00
parent d7e505d238
commit 5f973162f4
1 changed files with 152 additions and 418 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+152 -418
View File
@@ -1,463 +1,197 @@
# CCS Contributing Guide
# Contributing to CCS
Welcome! We're excited you're interested in contributing to CCS. This guide will help you get started.
CCS is a Bun + TypeScript CLI with a React dashboard. This guide is the shortest path to making a clean change without reverse-engineering the repo first.
## 🚀 Quick Start for First-Time Contributors
## Before You Start
**Never contributed before?** Start here:
- Open or claim an issue if the change is more than a typo.
- Branch from `dev`.
- Open PRs against `dev`.
- Use conventional commits.
- If you change user-facing behavior, update the docs that describe it.
1. **Find a good first issue**: Look for issues labeled [`good first issue`](https://github.com/kaitranntt/ccs/labels/good%20first%20issue)
2. **Read [CLAUDE.md](./CLAUDE.md)**: Understand the project architecture and v3.0 features
3. **Set up your environment**: See [Development Setup](#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
If you are new to the project, start with a docs fix, a focused bug fix, or an issue labeled `good first issue`.
**Questions?** Open a [GitHub Discussion](https://github.com/kaitranntt/ccs/discussions) - we're here to help!
## Repo Map
## Development Guidelines
| Area | Main paths | Typical follow-up |
| --- | --- | --- |
| CLI runtime | `src/`, `lib/`, `config/`, `scripts/` | Add or update tests in `tests/` |
| Dashboard UI | `ui/src/` | Run `cd ui && bun run validate` |
| Web server and config APIs | `src/web-server/`, `src/api/`, `src/config/` | Add unit or integration coverage |
| Documentation | `README.md`, `docs/`, `CONTRIBUTING.md` | Keep user-facing docs in sync |
| Static assets | `assets/` | Verify screenshots and references still match |
### Philosophy
Useful directories:
CCS follows these core principles:
- `tests/unit/` for focused logic tests
- `tests/integration/` for cross-module behavior
- `tests/npm/` for packaging checks
- `tests/native/` for shell and platform coverage
- `docs/` for architecture, roadmap, and internal implementation notes
- **YAGNI**: No features "just in case"
- **KISS**: Simple bash, no complexity
- **DRY**: One source of truth (config)
## Environment Setup
This tool does ONE thing well: enable instant switching between Claude accounts and alternative models.
### Prerequisites
### Code Standards
- Node.js `>=18`
- Bun `>=1.0`
- GitHub CLI (`gh`) if you want to open PRs from the terminal
#### 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**:
```bash
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**:
```bash
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**:
```bash
ccs glm --help
ccs /plan "test"
```
4. **Error handling**:
```bash
ccs invalid-profile # Should show error
ccs --invalid-flag # Should pass through to Claude
```
### Branching Strategy
#### Branch Hierarchy
```
main (production) ← dev (integration) ← feat/* | fix/* | docs/*
↑ ↑
│ └── All contributions merge here FIRST
│
└── Only: tested dev code OR hotfix/*
```
#### Branch Types
| Branch | Purpose | PRs Target | Releases To |
|--------|---------|------------|-------------|
| `main` | Production | From `dev` only | npm `@latest` |
| `dev` | Integration/testing | From `feat/*`, `fix/*` | npm `@dev` |
| `feat/*` | New features | → `dev` | - |
| `fix/*` | Bug fixes | → `dev` | - |
| `docs/*` | Documentation | → `dev` | - |
| `hotfix/*` | Critical fixes | → `main` directly | npm `@latest` |
#### Branch Naming Convention
```
<type>/<short-description>
# Examples:
feat/oauth-token-refresh
fix/doctor-missing-config
docs/update-installation-guide
hotfix/critical-security-fix
```
#### Development Workflow (Contributors)
### Clone and install
```bash
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/ccs.git
cd ccs
# 2. Add upstream remote
git remote add upstream https://github.com/kaitranntt/ccs.git
# 3. ALWAYS start from latest DEV (not main!)
git checkout dev
git pull upstream dev
# 4. Create feature branch FROM DEV
git checkout -b feat/my-feature # for features
git checkout -b fix/bug-name # for bug fixes
git checkout -b docs/update-readme # for documentation
bun install
cd ui && bun install && cd ..
```
# 5. Make changes with conventional commits
git commit -m "feat(scope): add new feature"
## Branching and PRs
# 6. Push to your fork
git push -u origin feat/my-feature
Create all normal contribution branches from `dev`.
# 7. Create PR targeting DEV (not main!)
gh pr create --base dev --title "feat(scope): add new feature"
# → After merge, your changes release to npm @dev for testing
# 8. Maintainers will promote tested dev to main
# → This triggers npm @latest release
# 9. After PR merged, clean up
```bash
git checkout dev
git pull upstream dev
git branch -d feat/my-feature
git checkout -b feat/short-description
```
#### Hotfix Workflow (Critical Production Fixes Only)
Use these prefixes:
- `feat/*` for features
- `fix/*` for bug fixes
- `docs/*` for documentation-only changes
Rules:
- Never commit directly to `main` or `dev`.
- Open PRs to `dev`, not `main`.
- Treat `hotfix/*` as maintainer-only emergency flow from `main`.
- Delete your branch after merge.
Example:
```bash
# Only for critical bugs in production!
# 1. Start from main
git checkout main
git pull upstream main
# 2. Create hotfix branch
git checkout -b hotfix/critical-bug
# 3. Fix and commit
git commit -m "fix: critical security vulnerability"
# 4. PR directly to main (skip dev)
gh pr create --base main --title "fix: critical security vulnerability"
# 5. After merge, sync to dev
# (Maintainers will handle this)
git push -u origin docs/contributing-refresh
gh pr create --base dev --title "docs(contributing): refresh contributor guide"
```
#### Rules
## Local Development
- **NEVER** commit directly to `main` or `dev`
- **ALWAYS** create branches from `dev` (not main)
- **ALWAYS** target PRs to `dev` (not main)
- **ONLY** `hotfix/*` branches target `main` directly
- **DELETE** branches after merge
### Safe test environment
### Submission Process
CCS reads and writes under `~/.ccs/`. Do not test against your real setup when developing.
#### Before Submitting
Unix:
1. Ensure branch is from `dev` (not main)
2. Ensure branch follows naming: `feat/*`, `fix/*`, `docs/*`
3. Run `bun run validate` - must pass
4. Rebase on latest dev: `git rebase dev`
5. Test on all platforms if possible
#### Pull Request Requirements
- **Target `dev` branch** (not main!) - unless hotfix
- Clear description of changes
- Testing instructions if applicable
- Link to relevant issues
- **All commits MUST follow conventional format** (enforced by husky)
- **Branch MUST follow naming convention** (`feat/*`, `fix/*`, etc.)
- Run `bun run validate` before submitting
#### Commit Message Style (MANDATORY)
**All commits MUST follow conventional commit format. Non-compliant commits are automatically rejected.**
```
type(scope): description
[optional body]
[optional footer]
```
**Commit types that trigger releases:**
| Type | Version Bump |
|------|--------------|
| `feat:` | MINOR (5.0.2 → 5.1.0) |
| `fix:` | PATCH (5.0.2 → 5.0.3) |
| `perf:` | PATCH |
| `feat!:` | MAJOR (5.0.2 → 6.0.0) |
**Commit types that DON'T trigger releases:**
`docs:`, `style:`, `refactor:`, `test:`, `chore:`, `ci:`, `build:`
**Examples:**
```bash
# Good - will be accepted
git commit -m "fix(installer): handle git worktree detection"
git commit -m "feat(config): support custom config location"
git commit -m "docs(readme): update installation instructions"
git commit -m "feat!: remove deprecated API" # Breaking change
export CCS_HOME="$(mktemp -d)"
```
# Bad - will be REJECTED by husky
git commit -m "fixed bug"
PowerShell:
```powershell
$env:CCS_HOME = Join-Path $env:TEMP ("ccs-" + [guid]::NewGuid())
```
If you touch code that reads CCS paths, route it through `getCcsDir()` in `src/utils/config-manager.ts` so tests stay isolated.
### Common workflows
```bash
bun run build # Compile CLI
bun run dev # Build server and start local config dashboard
bun run dev:symlink # Point global ccs to local build
bun run dev:unlink # Restore original global ccs
cd ui && bun run dev # Dashboard-only dev server
```
Use `bun run dev` from the repo root when working on the local dashboard experience behind `ccs config`.
## Validation
Run these before you open or update a PR:
```bash
bun run format
bun run lint:fix
bun run validate
bun run validate:ci-parity
```
If you changed the dashboard:
```bash
cd ui
bun run format
bun run validate
```
Helpful targeted commands:
```bash
bun run test:unit
bun run test:all
bun run test:native
bun run test:e2e
```
`bun run validate` is the main gate. It covers typechecking, linting, format checks, maintainability checks, and automated tests for the main project.
## What To Update With Your Change
### If you change CLI behavior
- Update the relevant `--help` output in `src/commands/`.
- Add or update automated coverage in `tests/`.
- Update `README.md` if the user workflow changed.
### If you change dashboard behavior
- Keep CLI and dashboard parity where the feature supports both.
- Update `ui/src/` and any affected tests.
- Run UI validation from `ui/`.
### If you change config, providers, or architecture
- Update the relevant docs in `docs/`.
- Mention migration or compatibility notes in the PR.
## Commit Style
All commits must use conventional commit format.
```bash
git commit -m "fix(doctor): handle missing config gracefully"
git commit -m "feat(cliproxy): add provider quota check"
git commit -m "docs(contributing): simplify contributor workflow"
```
Avoid:
```bash
git commit -m "fix stuff"
git commit -m "WIP"
git commit -m "updated stuff"
git commit -m "update file"
```
### Development Setup
## Release Notes
#### Local Development
Releases are automated with semantic-release.
```bash
# Clone your fork
git clone https://github.com/yourusername/ccs.git
cd ccs
- Merges to `dev` publish the `@dev` channel.
- Merges to `main` publish the `@latest` channel.
- Do not manually bump versions, create tags, or run manual `npm publish`.
# Create feature branch
git checkout -b your-feature-name
## Need Help?
# Option 1: Test with built binary
# Test locally with ./dist/ccs.js
# Option 2: Symlink for seamless testing (recommended)
bun run build
bun run dev:symlink # Symlinks global 'ccs' to dev version
# Now 'ccs' command uses your dev changes!
# Make changes
# Test with: ccs <command>
# When done developing:
bun run dev:unlink # Restores original global ccs
# Run tests
# Test with: ccs <command>
# Run tests
bun run test # All tests
bun run test:native # Native Unix tests only
```
#### Testing npm Package Locally
```bash
# 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
```bash
# 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](https://github.com/kaitranntt/ccs/issues) for:
- [`good first issue`](https://github.com/kaitranntt/ccs/labels/good%20first%20issue) - Great for first-time contributors
- [`help wanted`](https://github.com/kaitranntt/ccs/labels/help%20wanted) - We need your expertise!
- [`documentation`](https://github.com/kaitranntt/ccs/labels/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](./README.md) for usage examples
#### Communication Channels
- Primary: [GitHub Issues](https://github.com/kaitranntt/ccs/issues)
- Questions: [GitHub Discussions](https://github.com/kaitranntt/ccs/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](./CLAUDE.md)**: Technical architecture and v3.0 implementation details
- **[README.md](./README.md)**: User-facing documentation and examples
- **[GitHub Issues](https://github.com/kaitranntt/ccs/issues)**: Track bugs, features, and discussions
- **[VERSION](./VERSION)**: Current version number
## 🎯 Release Process (FULLY AUTOMATED)
**Releases are automated via semantic-release. DO NOT manually bump versions or create tags.**
### How Releases Work
1. **Write conventional commits** during development
2. **Merge PR to `main`** (or push to `dev`)
3. **CI automatically:**
- Analyzes commits since last release
- Determines version bump from commit types
- Updates CHANGELOG.md, VERSION, package.json
- Creates git tag
- Publishes to npm
- Creates GitHub release
### Release Channels
| Branch | npm Tag | Use Case |
|--------|---------|----------|
| `main` | `@latest` | Stable production releases |
| `dev` | `@dev` | Pre-release testing |
### Workflow
```bash
# Stable release
git checkout -b feat/my-feature
git commit -m "feat: add new feature"
gh pr create --base main
# → Merge PR → CI auto-releases to npm @latest
# Dev release
git checkout dev
git merge feat/experimental
git push origin dev
# → CI auto-releases to npm @dev
```
**NEVER DO:**
- `./scripts/bump-version.sh` (deprecated, emergency only)
- `git tag vX.Y.Z` (tags are auto-created)
- Manual `npm publish` (CI handles it)
## 📄 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.
- Bugs and features: https://github.com/kaitranntt/ccs/issues
- Questions and discussion: https://github.com/kaitranntt/ccs/discussions
- User-facing docs: [README.md](./README.md)
- Internal architecture notes: [docs/](./docs)