> ## Documentation Index
> Fetch the complete documentation index at: https://mako-docs.devinagiffy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Contributing
> Guidelines for contributing to Hitler
## Getting Started
1. Fork the repository on GitHub
2. Clone your fork locally
3. Follow the [Developer Setup](/development/setup) guide
4. Create a feature branch
```bash theme={null}
git checkout -b feature/your-feature-name
```
## Development Workflow
### 1. Make Your Changes
* Write your code following our [code style](#code-style)
* Add tests for new functionality
* Update documentation if needed
### 2. Run Quality Checks
Before committing, ensure all checks pass:
```bash theme={null}
# Type checking
pnpm type-check
# Linting
pnpm lint
# Tests
pnpm test
# Format code
pnpm format
```
### 3. Commit Your Changes
We follow [Conventional Commits](https://www.conventionalcommits.org/):
```bash theme={null}
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
| Type | Description |
| ---------- | ------------------------------------------------------- |
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, no code change |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `test` | Adding or updating tests |
| `chore` | Maintenance tasks |
### 4. Push and Create PR
```bash theme={null}
git push origin feature/your-feature-name
```
Then open a Pull Request on GitHub.
## 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
```typescript theme={null}
// Good
interface TaskInput {
title: string;
priority: number;
}
// Avoid
type TaskInput = {
title: any;
};
```
### Naming Conventions
| Type | Convention | Example |
| ---------------- | ---------------- | ----------------- |
| Files | kebab-case | `task-service.ts` |
| Classes | PascalCase | `TaskService` |
| Functions | camelCase | `createTask()` |
| Constants | SCREAMING\_SNAKE | `MAX_RETRIES` |
| Types/Interfaces | PascalCase | `TaskStatus` |
### File Organization
```typescript theme={null}
// 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
Use the same format as commits:
```
feat: add mood trend analysis
fix: resolve task draft expiration bug
```
### PR Description
Use the PR template provided. Include:
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
These rules are enforced in code review. PRs violating them will be rejected.
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
Write a brief design doc if the feature affects multiple packages.
If adding new data, update `packages/db/src/schema/`. Run `pnpm db:generate` to create
migrations.
Add Zod schemas to `packages/shared/src/schemas.ts`. Export enums from
`packages/shared/src/enums.ts`.
Add controller and service in `apps/api/src/modules/`. Include Swagger documentation.
Add typed methods to `packages/sdk/src/client.ts`.
Write unit tests for business logic. Write integration tests for API endpoints.
### 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
```typescript theme={null}
/**
* 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 {
// ...
}
```
### 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
Open an issue for bugs or feature requests
Use GitHub Discussions for questions
## Code of Conduct
* Be respectful and inclusive
* Focus on constructive feedback
* Help others learn and grow
* Assume good intentions