cloud-host/CONTRIBUTING.md

Contributing to CloudHost

Commit Conventions

This project follows Conventional Commits.

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

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

# Backend TypeScript
cd backend && npx tsc --noEmit

# Frontend TypeScript
cd frontend && npx tsc --noEmit

# Helm chart
helm lint backend/helm/cloudhost-app