Code of conduct

Enclaive EMCP - Engineering Code of Conduct

1. Pull Requests

Keep PRs Small and Focused

• A PR should do one thing. If you can't describe it in one sentence, it's too big.

• Aim for under 400 lines of changed code (excluding auto-generated files, tests, and lock files).

• If a feature is large, break it into a chain of smaller PRs that each leave the codebase in a working state.

• Prefer multiple small PRs over one large PR — smaller PRs get reviewed faster, merge cleaner, and are easier to revert.

PR Naming Convention

• Use a clear, descriptive title in imperative mood:

  • Add workload status polling to runner service

  • Fix Terraform plan output parsing for nested modules

  • Refactor finops cost aggregation to use batch queries

• Prefix with the service/area when it helps clarity:

  • [emcp_be] Add rate limiting to deployment endpoints

  • [emcp_ui] Fix cluster selector dropdown not updating

• Avoid vague titles like fix bug, updates, WIP, or changes.

PR Description

• Include what changed and why.

• Link the relevant ticket/issue.

• Add screenshots or screen recordings for UI changes.

• Call out anything reviewers should pay special attention to.

PR Review Expectations

• Every PR requires at least one approval before merge.

• Reviewers: respond within one business day.

• Authors: address all comments before requesting re-review.

• Use "Request Changes" for blocking issues, "Comment" for suggestions.

---

2. Naming Conventions

Variables and Functions

• Use camelCase for variables, functions, and method names: getUserClusters, workloadConfig.

• Use PascalCase for classes, interfaces, types, and components: WorkloadRunner, ClusterStatus.

• Use UPPER_SNAKE_CASE for constants and environment variables: MAX_RETRY_COUNT, TERRAFORM_TIMEOUT_MS.

• Boolean variables should read as a question: isDeployed, hasPermission, canRetry.

Names Should Be Descriptive

• Avoid single-letter variables (except i, j in simple loops).

• Avoid abbreviations unless universally understood (id, url, config are fine; wkld, tfrm are not).

• Name things for what they represent, not how they're implemented.

  • clustersByRegion not clusterMap

  • activeWorkloads not filteredList

File Naming

• NestJS services: <name>.service.ts, <name>.controller.ts, <name>.module.ts

• React components: <ComponentName>.tsx or <ComponentName>/index.tsx

• Test files: <name>.spec.ts (unit), <name>.e2e-spec.ts (e2e)

---

3. Testing Strategy

Unit Tests

• Every new service method and utility function must have unit tests.

• Mock external dependencies (DB, HTTP, cloud APIs) — unit tests must run fast and offline.

• Test behavior, not implementation — assert on outcomes, not internal calls.

• Aim for meaningful coverage, not 100%. Cover:

  • Happy path

  • Edge cases and boundary values

  • Error/failure scenarios

System / Integration Tests

• Services that interact with databases, message queues, or other services must have integration tests.

• Use test containers or dedicated test environments — never hit production resources.

• Integration tests validate that modules work together correctly (e.g., controller -> service -> repository).

End-to-End (E2E) Tests

• E2E tests run at the end of every development cycle, before a feature is considered "done".

• Use the emcp-e2e-test-suit to validate full user flows across services.

• A feature is not complete until its E2E tests pass on the CI pipeline.

• When adding a new feature or flow, add or update the corresponding E2E tests.

• E2E failures block the merge — do not skip or disable them without team discussion.

Test Naming

• Test names should describe the scenario and expected outcome:

  • should return 404 when workload does not exist

  • should aggregate costs by cluster when groupBy is set to cluster

• Avoid generic names like should work or test 1.

---

4. Development Workflow

Branch Naming

• feature/<ticket-id>-short-description — e.g., feature/EMCP-142-add-cost-alerts

• fix/<ticket-id>-short-description — e.g., fix/EMCP-203-terraform-timeout

• chore/<description> — for non-functional changes (deps, CI, configs)

Definition of Done

A task is considered done when:

1. Code is written and self-reviewed.

2. Unit tests are written and passing.

3. Integration/system tests are written where applicable and passing.

4. E2E tests are updated (if the change affects user flows) and passing.

5. PR is reviewed and approved.

6. No linting errors or type errors.

7. Documentation is updated if the change affects APIs or configuration.

Commit Messages

• Use imperative mood: Add, Fix, Refactor, Remove — not Added, Fixes, Removing.

• Keep the first line under 72 characters.

• Reference the ticket when relevant: Fix cost calculation rounding error (EMCP-301).

---

5. Code Quality

General Principles

• Don't leave dead code, commented-out blocks, or TODO comments without a linked ticket.

• Keep functions short and focused — if it scrolls off screen, consider breaking it up.

• Prefer explicit over clever. Code is read far more than it is written.

• Handle errors intentionally — don't swallow exceptions silently.

Code Reviews

• Review for correctness, readability, and maintainability — in that order.

• If you don't understand the code, that's a valid review comment.

• Praise good patterns when you see them — reviews aren't only for catching problems.

---

6. Communication

• If you're blocked, speak up early — don't spend a full day stuck.

• If a PR is urgent, say so in Slack and tag the reviewer directly.

• If you're going to miss a deadline or estimate, communicate proactively.

• Ask questions — no one knows everything, and asking is faster than guessing.

---

This is a living document. If something isn't working or is missing, open a PR to improve it.