# 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
```