keyhan
5f77c07183
- ARCHITECTURE.md: all modules, Helm charts, billing/lifecycle flow, WordPress - README.md: updated features, API endpoints, configuration, project structure - CHANGELOG.md: full changelog for all unreleased changes - CONTRIBUTING.md: commit conventions, documentation requirements, PR checklist
146 lines
4.0 KiB
Markdown
146 lines
4.0 KiB
Markdown
# Contributing to CloudHost
|
|
|
|
## Commit Conventions
|
|
|
|
This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
|
|
|
|
### Format
|
|
|
|
```
|
|
<type>(<scope>): <short description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
### Types
|
|
|
|
| Type | When to use |
|
|
|------|-------------|
|
|
| `feat` | New feature or capability |
|
|
| `fix` | Bug fix |
|
|
| `refactor` | Code change that neither fixes a bug nor adds a feature |
|
|
| `docs` | Documentation only changes |
|
|
| `test` | Adding or updating tests |
|
|
| `chore` | Build process, CI, dependency updates |
|
|
| `perf` | Performance improvement |
|
|
| `style` | Code style (formatting, semicolons, etc.) |
|
|
|
|
### Scopes
|
|
|
|
| Scope | Area |
|
|
|-------|------|
|
|
| `build` | Build service, Kaniko, Dockerfile generation |
|
|
| `helm` | Helm chart templates and values |
|
|
| `k8s` | Kubernetes service, cluster management |
|
|
| `billing` | Wallet, transactions, plans |
|
|
| `lifecycle` | Auto-suspend/delete scanner |
|
|
| `auth` | Authentication, JWT, guards |
|
|
| `apps` | Applications module |
|
|
| `deploy` | Deployments module |
|
|
| `frontend` | Next.js frontend |
|
|
| `docs` | Documentation files |
|
|
| `deps` | Dependency changes |
|
|
|
|
### Examples
|
|
|
|
```
|
|
feat(helm): add WordPress wp-content PVC template
|
|
fix(build): detect runtime from parent dir not zip file
|
|
feat(lifecycle): add cron-based app suspension scanner
|
|
docs: update ARCHITECTURE.md with billing flow
|
|
test(k8s): add buildHelmValues unit tests
|
|
refactor(billing): extract calculateCostForApp method
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation Requirements
|
|
|
|
### When to Update Docs
|
|
|
|
Every change **must** include documentation updates where applicable:
|
|
|
|
1. **New module/service** → Update `ARCHITECTURE.md` module table + project structure
|
|
2. **New API endpoint** → Update `README.md` API endpoints section
|
|
3. **New env variable** → Update `README.md` configuration table + `configuration.ts`
|
|
4. **New Helm template** → Update `ARCHITECTURE.md` Helm chart table
|
|
5. **Breaking change** → Add `BREAKING CHANGE:` footer in commit + update CHANGELOG
|
|
|
|
### CHANGELOG
|
|
|
|
Update `CHANGELOG.md` under `[Unreleased]` for every PR:
|
|
|
|
- **Added** — new features
|
|
- **Changed** — changes to existing functionality
|
|
- **Deprecated** — soon-to-be removed features
|
|
- **Removed** — removed features
|
|
- **Fixed** — bug fixes
|
|
- **Security** — vulnerability fixes
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### Branch Strategy
|
|
|
|
```
|
|
main ← production-ready
|
|
└── feat/* ← feature branches
|
|
└── fix/* ← bug fix branches
|
|
└── refactor/* ← refactoring branches
|
|
```
|
|
|
|
### PR Checklist
|
|
|
|
Before submitting a PR:
|
|
|
|
- [ ] Code compiles: `cd backend && npx tsc --noEmit`
|
|
- [ ] Frontend compiles: `cd frontend && npx tsc --noEmit`
|
|
- [ ] Helm chart lints: `helm lint backend/helm/cloudhost-app`
|
|
- [ ] Tests pass: `cd backend && npm test`
|
|
- [ ] CHANGELOG.md updated
|
|
- [ ] Documentation updated (if applicable)
|
|
- [ ] No `console.log` left in production code (use `Logger` service)
|
|
|
|
### Code Style
|
|
|
|
- **TypeScript strict mode** — no `any` unless explicitly justified
|
|
- **NestJS patterns** — use decorators, dependency injection, modules
|
|
- **Logging** — use NestJS `Logger` service, not `console.log`
|
|
- **Error handling** — use NestJS exceptions (`NotFoundException`, `BadRequestException`, etc.)
|
|
- **Naming** — `camelCase` for variables/methods, `PascalCase` for classes/types, `kebab-case` for files
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
cd backend && npm test
|
|
```
|
|
|
|
Tests are co-located with source files (`*.spec.ts`):
|
|
|
|
| Test file | Coverage |
|
|
|-----------|----------|
|
|
| `build.service.spec.ts` | WordPress Dockerfile, runtime detection, PVC cleanup |
|
|
| `helm.service.spec.ts` | Chart path resolution, temp file management |
|
|
| `kubernetes.service.spec.ts` | Helm values building, password generation |
|
|
| `clusters.service.spec.ts` | Default cluster selection, delete/reassign |
|
|
|
|
### Validation
|
|
|
|
```bash
|
|
# Backend TypeScript
|
|
cd backend && npx tsc --noEmit
|
|
|
|
# Frontend TypeScript
|
|
cd frontend && npx tsc --noEmit
|
|
|
|
# Helm chart
|
|
helm lint backend/helm/cloudhost-app
|
|
```
|