sencho/CONTRIBUTING.md

Contributing to Sencho

Thank you for your interest in contributing to Sencho!

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/Sencho.git
3. Create a branch: git checkout -b feature/your-feature
4. Install dependencies:

   cd backend && npm install
   cd ../frontend && npm install
   

5. Start the dev servers:

   cd backend && npm run dev    # Express + nodemon on :1852
   cd frontend && npm run dev   # Vite on :5173
   

Project Layout

backend/
  src/
    routes/       # One router per feature group (stacks, nodes, fleet, ...)
    services/     # Business logic singletons (ComposeService, DockerController, ...)
    middleware/   # Auth, tier gates, audit log, node context
    websocket/    # Upgrade handlers for log streaming, host console, proxy tunnels
frontend/
  src/
    components/   # Page-level and shared UI components
    context/      # Auth, node selection, and other React contexts
    hooks/        # Shared React hooks
    lib/          # apiFetch wrapper and other utilities

Read CLAUDE.md for full coding standards, architecture rules, and the pre-commit checklist.

Development

• Backend: Node.js + Express + TypeScript in backend/
• Frontend: React 19 + Vite + TypeScript in frontend/
• Tests: cd backend && npm test (Vitest) and npm run test:e2e (Playwright)
• Lint: npm run lint in both backend/ and frontend/
• Type check: Run cd backend && npx tsc --noEmit (and the frontend equivalent) before every commit. The CI build will reject type errors.

TypeScript Standards

The project uses strict: true. Write code that compiles without any casts or @ts-ignore. If a library lacks types, import @types/... or use unknown with narrowing.

Tier-Gated Features

Sencho has three tiers: Community, Skipper, and Admiral. We welcome contributions to all tiers! Often, enterprise users will contribute features they need for their own infrastructure.

If your change adds a feature that belongs behind a tier gate, use the guards from backend/src/middleware/tierGates.ts:

if (!requirePaid(req, res)) return;    // Skipper and above
if (!requireAdmiral(req, res)) return; // Admiral only

Call the guard at the top of the route handler with an early return. Both guards handle proxy-forwarded tier headers automatically.

Note on Tiers and Monetization:

• Community Tier: If you contribute a feature to the free/Community tier, it stays in the Community tier. We will never take your community contribution and move it behind a paywall.
• Commercial Tiers: By contributing to a Skipper or Admiral feature, you acknowledge that your code will be part of Sencho's commercial offering.

Before writing code for a new gated feature, please open an issue to discuss it with the maintainers. You will also be required to sign our Contributor License Agreement (CLA) when you open your first Pull Request.

Pull Request Process

• All PRs target main
• Ensure CI passes before requesting review
• Use Conventional Commits for commit messages
• Update documentation if your change affects user-facing behavior
• Add tests for new functionality
• Keep PRs focused: one feature or fix per PR
• Do not edit CHANGELOG.md directly. It is generated from conventional-commit subjects by release-please. If a user-facing change needs more context, enrich the auto-opened Release PR description before merging.

Reporting Bugs

Use the bug report template. Include: deployment method, Sencho version, browser (for UI issues), steps to reproduce, and expected vs actual behavior.

Code Style

• TypeScript with strict: true: no any casts or @ts-ignore
• ESLint 9 flat config for both backend and frontend
• Tailwind CSS + shadcn/ui for frontend styling
• Follow existing patterns in the codebase