Contributing

Getting Started

BASH Copy
# Fork and clone
git clone https://github.com/<your-username>/ctx-sync.git
cd ctx-sync

# Install dependencies (includes Husky git hooks)
npm install

# Build shared packages
npm run build -w packages/shared

# Verify everything works
npm run typecheck
npm run lint
npm run test:unit -w apps/cli

Branching Strategy

We use a structured branching model. All work happens on feature branches that merge into develop, which is then promoted to main for releases.

feat/<name>  ──squash merge──>  develop  ──merge──>  main  ──tag──>  vX.Y.Z

1. Create a feature branch from develop: git checkout -b feat/my-feature develop
2. Do your work with atomic commits
3. Open a PR targeting develop (never directly to main)
4. After approval, the PR is squash-merged into develop

Branch Naming

Commit Convention

This project enforces Conventional Commits via commitlint. Every commit must follow this format:

<type>[optional scope]: <description>

Allowed Types

Examples

feat(cli): add --force flag to init command
fix(ci): align release workflow node matrix
docs(website): update FAQ for v1.2.0
test: add coverage for restore --no-pull

Pre-commit Hooks

Husky runs these checks on every commit — if any fail, the commit is rejected:

1. TypeScript typecheck — tsc --noEmit across all packages
2. ESLint — linting across all packages
3. Unit tests — CLI + shared package tests
4. Commitlint — validates your commit message format

Running Tests

BASH Copy
# Individual suites
npm run test:unit -w apps/cli          # ~800 unit tests
npm run test:integration -w apps/cli   # Integration tests
npm run test:e2e -w apps/cli           # End-to-end tests
npm run test:security -w apps/cli      # ~260 security tests
npm run test:performance -w apps/cli   # Benchmarks

# Everything at once
npm run test:all

# Watch mode (great during development)
npm run test:watch -w apps/cli

Security Considerations

ctx-sync handles encryption keys and secrets. When contributing:

• Never log, print, or expose private keys or decrypted secrets
• Never pass secrets as CLI arguments (use stdin or env vars)
• Ensure file permissions are enforced (key: 0o600, config dir: 0o700)
• All new state must be encrypted before writing to disk or Git
• Do not commit .env files, credentials, or key material

CI Pipeline

Every PR triggers these checks — all must pass to merge:

The main branch is protected — direct pushes are blocked and all status checks must pass via PR.

Submitting a Pull Request

1. Ensure your branch is up to date with develop
2. Run the checks locally:

   BASH Copy
   npm run typecheck && npm run lint && npm run test:unit -w apps/cli
   

3. Push your branch and open a PR targeting develop
4. Fill in the PR with a Summary (what and why) and Test plan (how you verified)
5. Address review feedback

Reporting Issues

• Use GitHub Issues
• Include: OS, Node version, ctx-sync version, steps to reproduce
• For security vulnerabilities, email the maintainer directly — do not open a public issue

Links

• Full CONTRIBUTING.md
• GitHub Repository
• Open an Issue
• npm Package