Contributing

​

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Follow the Developer Setup guide
4. Create a feature branch

git checkout -b feature/your-feature-name

​

Development Workflow

​

1. Make Your Changes

• Write your code following our code style
• Add tests for new functionality
• Update documentation if needed

​

2. Run Quality Checks

# Type checking
pnpm type-check

# Linting
pnpm lint

# Tests
pnpm test

# Format code
pnpm format

​

3. Commit Your Changes

git commit -m "feat: add mood trend analysis"
git commit -m "fix: resolve task draft expiration bug"
git commit -m "docs: update API reference for flags"

​

Commit Types

​

4. Push and Create PR

git push origin feature/your-feature-name

​

Code Style

​

TypeScript

• Use TypeScript strict mode
• Prefer interface over type for object shapes
• Use const by default, let when reassignment is needed
• No any types - use unknown and type guards

// Good
interface TaskInput {
  title: string;
  priority: number;
}

// Avoid
type TaskInput = {
  title: any;
};

​

Naming Conventions

​

File Organization

// 1. Imports (external, then internal)
import { Injectable } from "@nestjs/common";
import { TasksRepository } from "./tasks.repository";

// 2. Types and interfaces
interface CreateTaskDto {
  title: string;
}

// 3. Constants
const DEFAULT_PRIORITY = 3;

// 4. Main export (class, function, etc.)
@Injectable()
export class TasksService {
  // ...
}

​

Pull Request Guidelines

​

PR Title

feat: add mood trend analysis
fix: resolve task draft expiration bug

​

PR Description

1. Summary - What does this PR do?
2. Changes - Bullet points of specific changes
3. Testing - How was this tested?
4. Screenshots - If UI changes

​

Review Process

1. At least one approval required
2. All CI checks must pass
3. No merge conflicts
4. Squash merge to main

​

Architecture Guidelines

​

Non-Negotiable Rules

1. Bot apps MUST use SDK - Never call raw REST from adapters
2. LLM calls only in API - Platform adapters never call LLMs directly
3. DB access only in API - No direct database access from bots or web
4. No secrets in DB - Platform tokens in Cloudflare KV only
5. Human confirmation required - LLM creates drafts, user confirms

​

Adding a New Feature

​

Adding a New Package

1. Create the package directory in /packages
2. Add package.json with proper naming (@hitler/package-name)
3. Add to pnpm-workspace.yaml if not auto-detected
4. Export from src/index.ts
5. Add tsconfig.json extending ../../tsconfig.base.json

​

Testing Requirements

​

New Features

• Unit tests for all business logic
• Integration tests for API endpoints
• Update existing tests if behavior changes

​

Bug Fixes

• Add a test that reproduces the bug
• The test should fail before the fix and pass after

​

Minimum Coverage

• New code should have 80%+ coverage
• Don’t decrease overall coverage

​

Documentation

​

Code Documentation

• Add JSDoc comments to public functions
• Include @param and @returns tags
• Add @example for complex functions

/**
 * Confirms a task draft and creates the actual task.
 *
 * @param draftId - The ID of the draft to confirm
 * @param userId - The ID of the user confirming
 * @returns The created task
 * @throws {BadRequestException} If the draft is expired or belongs to another user
 *
 * @example
 * const task = await tasksService.confirmDraft("draft-123", "user-456");
 */
async confirmDraft(draftId: string, userId: string): Promise<Task> {
  // ...
}

​

API Documentation

• Add Swagger decorators to all endpoints
• Include request/response examples
• Document error responses

​

User Documentation

• Update /docs if the feature is user-facing
• Add to guides if it changes workflow
• Update API reference for new endpoints

​

Getting Help

​

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help others learn and grow
• Assume good intentions