From 5f973162f4a24af8dd6cea120c7e5bb126b6d205 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Tue, 17 Mar 2026 15:29:21 -0400 Subject: [PATCH 1/5] docs(contributing): refresh contributor workflow --- CONTRIBUTING.md | 570 +++++++++++++----------------------------------- 1 file changed, 152 insertions(+), 418 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e45bcb1d..d3f81539 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 - -``` -/ - -# 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 - -# When done developing: -bun run dev:unlink # Restores original global ccs - -# Run tests -# Test with: ccs - -# 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. \ No newline at end of file +- 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) From 462d382c9391a17677095c9646954bf57668c802 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Tue, 17 Mar 2026 15:32:45 -0400 Subject: [PATCH 2/5] docs(community): add GitHub contribution templates --- .github/CODE_OF_CONDUCT.md | 40 ++++++++ .github/ISSUE_TEMPLATE/bug-report.yml | 101 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/documentation.yml | 44 +++++++++ .github/ISSUE_TEMPLATE/feature-request.yml | 69 ++++++++++++++ .github/pull_request_template.md | 25 +++++ CONTRIBUTING.md | 1 + 7 files changed, 285 insertions(+) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..37b1b341 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,40 @@ +# CCS Code of Conduct + +CCS is a technical project. Keep discussion respectful, constructive, and focused on improving the work. + +## Expected Behavior + +- Be respectful in issues, pull requests, reviews, and discussions. +- Assume good intent and ask clarifying questions before escalating. +- Give feedback that is specific, technical, and actionable. +- Be patient with contributors who are new to the codebase or toolchain. +- Respect maintainers' time by keeping reports reproducible and well scoped. + +## Unacceptable Behavior + +- Harassment, discrimination, or hate speech +- Personal attacks, insults, or hostile dogpiling +- Publishing private information, credentials, logs, or screenshots that expose sensitive data +- Spam, repeated derailment, or intentionally disruptive behavior +- Sexualized language or unwelcome sexual attention + +## Scope + +This applies to project spaces, including: + +- GitHub issues +- Pull requests and review comments +- Discussions +- Any other repository-managed collaboration channel + +## Enforcement + +Maintainers may edit or remove content, lock conversations, close threads, reject contributions, or block participants when needed to protect the project and contributors. + +For non-sensitive concerns, open a GitHub Discussion or issue. + +For sensitive concerns, do not post details publicly. Ask a maintainer for a private reporting path first and keep the initial message minimal. + +## Practical Rule + +Critique code, behavior, and decisions. Do not attack people. diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 00000000..d134cfd1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,101 @@ +name: Bug report +description: Report a reproducible problem in the CLI, dashboard, config flow, or packaging. +title: "bug: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for reporting this. Keep the report concrete and reproducible. + - type: dropdown + id: area + attributes: + label: Affected area + description: Pick the closest area. + options: + - CLI runtime + - Dashboard UI + - Config or auth flow + - Provider integration + - Install or packaging + - Documentation + validations: + required: true + - type: textarea + id: summary + attributes: + label: What broke? + description: Brief summary of the problem. + placeholder: Running `ccs config --host 0.0.0.0` prints the wrong reachable URL on macOS. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction steps + description: Exact steps, commands, inputs, and settings needed to reproduce. + placeholder: | + 1. Run `ccs ...` + 2. Open ... + 3. Observe ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: input + id: version + attributes: + label: CCS version + description: Output of `ccs --version` + placeholder: 7.54.0 + validations: + required: true + - type: dropdown + id: os + attributes: + label: Operating system + options: + - macOS + - Linux + - Windows + - Other + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment details + description: Include Node.js version, Bun version, shell, terminal, and anything else relevant. + placeholder: | + Node.js: + Bun: + Shell: + Terminal: + - type: textarea + id: logs + attributes: + label: Logs, screenshots, or terminal output + description: Redact tokens, cookies, email addresses, and any private config before posting. + render: shell + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched existing issues first. + required: true + - label: I removed secrets and private data from logs/screenshots. + required: true + - label: I can still reproduce this on the latest released or dev build. + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..312d0210 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Questions and discussion + url: https://github.com/kaitranntt/ccs/discussions + about: Use Discussions for open-ended questions, support requests, and idea shaping. diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 00000000..cb3cd87f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,44 @@ +name: Documentation improvement +description: Report missing, outdated, or confusing docs. +title: "docs: " +labels: + - documentation +body: + - type: dropdown + id: area + attributes: + label: Documentation area + options: + - README + - CONTRIBUTING guide + - Local docs in docs/ + - Command help output + - Dashboard copy or labels + - Other + validations: + required: true + - type: input + id: location + attributes: + label: File or page + description: Path or URL if you know it. + placeholder: README.md or docs/cursor-integration.md + - type: textarea + id: problem + attributes: + label: What is wrong or unclear? + placeholder: The guide still says to use an old command/path that no longer exists. + validations: + required: true + - type: textarea + id: suggestion + attributes: + label: Suggested improvement + placeholder: Replace it with ... + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I checked whether this is already covered elsewhere in the repo. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 00000000..6e63b442 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,69 @@ +name: Feature request +description: Suggest a focused improvement for the CLI, dashboard, or contributor workflow. +title: "feat: " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Feature requests land faster when they describe the user problem first and stay narrow. + - type: dropdown + id: area + attributes: + label: Affected area + options: + - CLI runtime + - Dashboard UI + - Config or auth flow + - Provider integration + - Install or packaging + - Documentation + - Contributor workflow + validations: + required: true + - type: textarea + id: problem + attributes: + label: What problem are you trying to solve? + placeholder: I manage multiple profiles, but ... + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + placeholder: Add a command or dashboard control that ... + validations: + required: true + - type: textarea + id: user-flow + attributes: + label: Suggested user flow + description: Show the command, screen, or sequence you expect. + placeholder: | + CLI: + 1. `ccs ...` + + Dashboard: + 1. Open ... + 2. Click ... + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Existing workaround, rejected approach, or why current behavior is not enough. + - type: textarea + id: context + attributes: + label: Additional context + description: Mockups, screenshots, links to related issues, or compatibility notes. + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched existing issues and discussions first. + required: true + - label: This request describes a concrete user problem, not just a broad idea dump. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..b3c8b996 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +## Summary + +- + +## Testing + +- [ ] `bun run validate` +- [ ] `bun run validate:ci-parity` +- [ ] `cd ui && bun run validate` if UI changed +- [ ] Not run + +## Checklist + +- [ ] Base branch is `dev` unless this is an approved hotfix +- [ ] Branch name follows `feat/*`, `fix/*`, `docs/*`, or approved hotfix naming +- [ ] Relevant `--help` output updated if CLI behavior changed +- [ ] Tests added or updated if behavior changed +- [ ] README or local docs updated if user-facing behavior changed +- [ ] No secrets, tokens, or private config data are included + +## Docs Impact + +Docs impact: `none | minor | major` + +Action: `no update needed` or describe what doc was updated diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3f81539..e985452a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -195,3 +195,4 @@ Releases are automated with semantic-release. - Questions and discussion: https://github.com/kaitranntt/ccs/discussions - User-facing docs: [README.md](./README.md) - Internal architecture notes: [docs/](./docs) +- Community expectations: [`.github/CODE_OF_CONDUCT.md`](./.github/CODE_OF_CONDUCT.md) From f0f5a9cf98ca5bc342f2ab2b47c35ebd8e4abee9 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Tue, 17 Mar 2026 15:36:34 -0400 Subject: [PATCH 3/5] docs(community): soften contributor requirements --- .github/ISSUE_TEMPLATE/bug-report.yml | 22 ++++------------------ .github/ISSUE_TEMPLATE/documentation.yml | 7 ++++--- .github/ISSUE_TEMPLATE/feature-request.yml | 9 ++------- .github/pull_request_template.md | 4 ++++ CONTRIBUTING.md | 8 +++++--- 5 files changed, 19 insertions(+), 31 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index d134cfd1..24edae15 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -7,7 +7,8 @@ body: - type: markdown attributes: value: | - Thanks for reporting this. Keep the report concrete and reproducible. + Thanks for reporting this. Use as much of this template as you can. + A partial but useful report is better than no report. - type: dropdown id: area attributes: @@ -20,8 +21,6 @@ body: - Provider integration - Install or packaging - Documentation - validations: - required: true - type: textarea id: summary attributes: @@ -34,33 +33,25 @@ body: id: reproduction attributes: label: Reproduction steps - description: Exact steps, commands, inputs, and settings needed to reproduce. + description: Exact steps are ideal, but rough steps are still helpful. placeholder: | 1. Run `ccs ...` 2. Open ... 3. Observe ... - validations: - required: true - type: textarea id: expected attributes: label: Expected behavior - validations: - required: true - type: textarea id: actual attributes: label: Actual behavior - validations: - required: true - type: input id: version attributes: label: CCS version - description: Output of `ccs --version` + description: Output of `ccs --version`, if you have it placeholder: 7.54.0 - validations: - required: true - type: dropdown id: os attributes: @@ -70,8 +61,6 @@ body: - Linux - Windows - Other - validations: - required: true - type: textarea id: environment attributes: @@ -94,8 +83,5 @@ body: label: Before submitting options: - label: I searched existing issues first. - required: true - label: I removed secrets and private data from logs/screenshots. - required: true - label: I can still reproduce this on the latest released or dev build. - required: false diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml index cb3cd87f..1b4b97aa 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -4,6 +4,10 @@ title: "docs: " labels: - documentation body: + - type: markdown + attributes: + value: | + Small or rough documentation reports are welcome. You do not need to fill every field. - type: dropdown id: area attributes: @@ -15,8 +19,6 @@ body: - Command help output - Dashboard copy or labels - Other - validations: - required: true - type: input id: location attributes: @@ -41,4 +43,3 @@ body: label: Before submitting options: - label: I checked whether this is already covered elsewhere in the repo. - required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml index 6e63b442..57c89761 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -8,6 +8,7 @@ body: attributes: value: | Feature requests land faster when they describe the user problem first and stay narrow. + Rough ideas are still welcome if they are grounded in a real workflow or pain point. - type: dropdown id: area attributes: @@ -20,8 +21,6 @@ body: - Install or packaging - Documentation - Contributor workflow - validations: - required: true - type: textarea id: problem attributes: @@ -32,10 +31,8 @@ body: - type: textarea id: proposal attributes: - label: Proposed solution + label: Proposed solution or direction placeholder: Add a command or dashboard control that ... - validations: - required: true - type: textarea id: user-flow attributes: @@ -64,6 +61,4 @@ body: label: Before submitting options: - label: I searched existing issues and discussions first. - required: true - label: This request describes a concrete user problem, not just a broad idea dump. - required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b3c8b996..3ed3a780 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,6 +4,8 @@ ## Testing +Use what applies. If you skipped something, add a short note instead of forcing it. + - [ ] `bun run validate` - [ ] `bun run validate:ci-parity` - [ ] `cd ui && bun run validate` if UI changed @@ -11,6 +13,8 @@ ## Checklist +Check what applies. Not every item is relevant for every PR. + - [ ] Base branch is `dev` unless this is an approved hotfix - [ ] Branch name follows `feat/*`, `fix/*`, `docs/*`, or approved hotfix naming - [ ] Relevant `--help` output updated if CLI behavior changed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e985452a..b14087aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ CCS is a Bun + TypeScript CLI with a React dashboard. This guide is the shortest ## Before You Start -- Open or claim an issue if the change is more than a typo. +- An issue is helpful for medium or large changes, but small fixes and docs updates can go straight to a PR. - Branch from `dev`. - Open PRs against `dev`. - Use conventional commits. @@ -116,7 +116,7 @@ Use `bun run dev` from the repo root when working on the local dashboard experie ## Validation -Run these before you open or update a PR: +If you can, run these before you open or update a PR: ```bash bun run format @@ -144,6 +144,8 @@ 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. +If you cannot run the full suite, that is still fine for early or docs-only PRs. Just say what you did run, or what blocked you, in the PR. + ## What To Update With Your Change ### If you change CLI behavior @@ -165,7 +167,7 @@ bun run test:e2e ## Commit Style -All commits must use conventional commit format. +CCS uses conventional commits because the release and workflow tooling depend on them. ```bash git commit -m "fix(doctor): handle missing config gracefully" From 9a44f53c15014499ebc132ffde8619b4be92df91 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Tue, 17 Mar 2026 15:42:30 -0400 Subject: [PATCH 4/5] docs(readme): highlight hosted docs hub --- CONTRIBUTING.md | 3 ++- README.md | 13 ++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b14087aa..e469fbdd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ If you are new to the project, start with a docs fix, a focused bug fix, or an i | 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 | +| Documentation | `https://docs.ccs.kaitran.ca`, `README.md`, `docs/`, `CONTRIBUTING.md` | Keep user-facing docs in sync | | Static assets | `assets/` | Verify screenshots and references still match | Useful directories: @@ -195,6 +195,7 @@ Releases are automated with semantic-release. - Bugs and features: https://github.com/kaitranntt/ccs/issues - Questions and discussion: https://github.com/kaitranntt/ccs/discussions +- Hosted docs: https://docs.ccs.kaitran.ca - User-facing docs: [README.md](./README.md) - Internal architecture notes: [docs/](./docs) - Community expectations: [`.github/CODE_OF_CONDUCT.md`](./.github/CODE_OF_CONDUCT.md) diff --git a/README.md b/README.md index 69391b4f..815aa9fb 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Run Claude, Gemini, GLM, and any Anthropic-compatible API - concurrently, withou [![npm](https://img.shields.io/npm/v/@kaitranntt/ccs?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@kaitranntt/ccs) [![PoweredBy](https://img.shields.io/badge/PoweredBy-ClaudeKit-C15F3C?style=for-the-badge)](https://claudekit.cc?ref=HMNKXOHN) -**[Features & Pricing](https://ccs.kaitran.ca)** | **[Documentation](https://docs.ccs.kaitran.ca)** +**[Features & Pricing](https://ccs.kaitran.ca)** | **[Documentation Hub](https://docs.ccs.kaitran.ca)** @@ -29,6 +29,9 @@ Run Claude, Gemini, GLM, and any Anthropic-compatible API - concurrently, withou ## Quick Start +Looking for the full setup guide, command reference, provider guides, or troubleshooting? +Start at **https://docs.ccs.kaitran.ca**. + ### 1. Install ```bash @@ -608,10 +611,14 @@ Notes:
-## Documentation +## Documentation Hub + +If you are not sure where to start, open **https://docs.ccs.kaitran.ca** first. +The hosted docs are the best entry point for setup, command reference, provider guides, and troubleshooting. | Topic | Link | |-------|------| +| Docs Home | [docs.ccs.kaitran.ca](https://docs.ccs.kaitran.ca) | | Installation | [docs.ccs.kaitran.ca/getting-started/installation](https://docs.ccs.kaitran.ca/getting-started/installation) | | Configuration | [docs.ccs.kaitran.ca/getting-started/configuration](https://docs.ccs.kaitran.ca/getting-started/configuration) | | OAuth Providers | [docs.ccs.kaitran.ca/providers/oauth-providers](https://docs.ccs.kaitran.ca/providers/oauth-providers) | @@ -673,6 +680,6 @@ MIT License - see [LICENSE](LICENSE). --- -**[ccs.kaitran.ca](https://ccs.kaitran.ca)** | [Report Issues](https://github.com/kaitranntt/ccs/issues) | [Star on GitHub](https://github.com/kaitranntt/ccs) +**[ccs.kaitran.ca](https://ccs.kaitran.ca)** | **[docs.ccs.kaitran.ca](https://docs.ccs.kaitran.ca)** | [Report Issues](https://github.com/kaitranntt/ccs/issues) | [Star on GitHub](https://github.com/kaitranntt/ccs) From 57af64b7d21248398ceabf5dbcb4a0012a3e7ef0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 17 Mar 2026 19:55:37 +0000 Subject: [PATCH 5/5] chore(release): 7.54.0-dev.10 [skip ci] --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 52c03bb5..388b664b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@kaitranntt/ccs", - "version": "7.54.0-dev.9", + "version": "7.54.0-dev.10", "description": "Claude Code Switch - Instant profile switching between Claude Sonnet 4.5 and GLM 4.6", "keywords": [ "cli",