mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-08 18:05:10 +00:00
Anso
bb50bed071
README: rewrite to lead with differentiation rather than a flat feature list. Add "Why Sencho?" section covering the four key competitive advantages (Pilot Agent NAT traversal, auto-heal self-healing, atomic deployments, automation-first model). Expand feature coverage from 8 bullets to six grouped domains reflecting the full 38-feature surface. Add architecture note, docker run one-liner, tier comparison table (Community/Skipper/Admiral), and docs link section. Drop stale CI badge; add Docker Pulls badge. CONTRIBUTING: add project layout reference, tier-gate usage guide, TypeScript strictness reminder, and pointer to CLAUDE.md for full coding standards. SECURITY: update supported versions table from stale "0.2.x+" to current "latest release" policy with a note on self-hosted update cadence.
83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# 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:
|
|
```bash
|
|
cd backend && npm install
|
|
cd ../frontend && npm install
|
|
```
|
|
5. Start the dev servers:
|
|
```bash
|
|
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](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. If your change adds a feature that belongs behind a tier gate, use the guards from `backend/src/middleware/tierGates.ts`:
|
|
|
|
```typescript
|
|
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.
|
|
|
|
## Pull Request Process
|
|
|
|
- All PRs target `main`
|
|
- Ensure CI passes before requesting review
|
|
- Use [Conventional Commits](https://www.conventionalcommits.org/) 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](https://github.com/AnsoCode/Sencho/issues/new?template=bug_report.yml). 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
|