CONTRIBUTING.md
Rama main · réplica de lectura del repositorio original.
# Contributing to Comp AI
Contributions are what makes the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
## House rules
- Before submitting a new issue or PR, check if it already exists in [issues](https://github.com/trycompai/comp/issues) or [PRs](https://github.com/trycompai/comp/pulls).
- GitHub issues: take note of the `🚨 needs approval` label.
- **For Contributors**:
- Feature Requests: Wait for a core member to approve and remove the `🚨 needs approval` label before you start coding or submit a PR.
- Bugs, Security, Performance, Documentation, etc.: You can start coding immediately, even if the `🚨 needs approval` label is present. This label mainly concerns feature requests.
- **Our Process**:
- Issues from non-core members automatically receive the `🚨 needs approval` label.
- We greatly value new feature ideas. To ensure consistency in the product's direction, they undergo review and approval.
## Priorities
<table>
<tr>
<td>
Type of Issue
</td>
<td>
Priority
</td>
</tr>
<tr>
<td>
Minor improvements, non-core feature requests
</td>
<td>
<a href="https://github.com/trycompai/comp/issues?q=is:issue+is:open+sort:updated-desc+label:%22Low+priority%22">
<img src="https://img.shields.io/badge/-Low%20Priority-green">
</a>
</td>
</tr>
<tr>
<td>
Confusing UX (... but working)
</td>
<td>
<a href="https://github.com/trycompai/comp/issues?q=is:issue+is:open+sort:updated-desc+label:%22Medium+priority%22">
<img src="https://img.shields.io/badge/-Medium%20Priority-yellow">
</a>
</td>
</tr>
<tr>
<td>
Core Features (Booking page, availability, timezone calculation)
</td>
<td>
<a href="https://github.com/trycompai/comp/issues?q=is:issue+is:open+sort:updated-desc+label:%22High+priority%22">
<img src="https://img.shields.io/badge/-High%20Priority-orange">
</a>
</td>
</tr>
<tr>
<td>
Core Bugs (Login, Booking page, Emails are not working)
</td>
<td>
<a href="https://github.com/trycompai/comp/issues?q=is:issue+is:open+sort:updated-desc+label:Urgent">
<img src="https://img.shields.io/badge/-Urgent-red">
</a>
</td>
</tr>
</table>
## Developing
The development branch is `dev`. This is the branch that all pull
requests should be made against. We will merge into main every week.
To develop locally:
1. [Fork](https://github.com/trycompai/comp/fork/) this repository to your
own GitHub account and then
[clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
2. Create a new branch:
```sh
git checkout -b MY_BRANCH_NAME
```
3. Install bun:
https://bun.sh/docs/installation
4. Install the dependencies with:
```sh
bun i
```
5. Set up your `.env` file:
- Duplicate `.env.example` to `.env`.
- Use `openssl rand -base64 32` to generate a key and add it under `SECRET_KEY` in the `.env` file.
- Setup Trigger.dev
- CD into apps/app and run `bunx trigger.dev@latest login`, then `bunx trigger.dev@latest dev`
- Use `openssl rand -base64 32` to generate a key and add it under `TRIGGER_SECRET_KEY` in the `.env` file.
6. Start developing and watch for code changes:
```sh
bun run dev
```
## Building
You can build the project with:
```bash
bun run build
```
Please be sure that you can make a full production build before pushing code.
## Testing
Coming soon.
### Running tests
Coming soon.
#### Resolving issues
## Linting
To check the formatting of your code:
```sh
bun run lint
```
If you get errors, be sure to fix them before committing.
## Adding or modifying API endpoints
Every endpoint in `apps/api/src/` ships to three places: the public OpenAPI spec (`packages/docs/openapi.json`), the customer-facing MCP server published as `@trycompai/mcp-server` on npm, and the runtime `ValidationPipe`. Endpoints that break the contract either silently fail for AI agents (Claude Desktop, Cursor, Codex, etc.) or reject requests at runtime.
**Read the full contract before adding a body-accepting endpoint:**
- AI tool users: [`.claude/skills/api-endpoint-contract/SKILL.md`](.claude/skills/api-endpoint-contract/SKILL.md) (Claude auto-loads) or [`.cursor/rules/api-endpoint-contract.mdc`](.cursor/rules/api-endpoint-contract.mdc) (Cursor auto-loads).
- For Codex/ChatGPT and human reading: see the "API Endpoint Contract" section in [`AGENTS.md`](AGENTS.md).
**Short checklist for every body endpoint:**
1. DTO is a **class** (not interface, not inline type).
2. Every field has **both** `@ApiProperty`/`@ApiPropertyOptional` and a class-validator decorator (`@IsString`, `@IsOptional`, `@IsObject`, `@IsArray`, etc.).
3. `@ApiBody({ type: DtoClass })` on the endpoint.
4. `@ApiOperation.description` ≤ 240 chars (truncator in `seo-text.ts`).
5. Long-running ops return a run handle and document the poll target — don't make agents wait synchronously.
6. File uploads accept an `s3Key` field (presigned upload path) — never base64 inline from agents.
7. After your change: `bun run --filter '@trycompai/api' dev` regenerates `packages/docs/openapi.json` on boot — **commit it with your PR**. The daily Speakeasy CI reads from that file.
## Making a Pull Request
- Be sure to [check the "Allow edits from maintainers" option](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) while creating your PR.
- If your PR refers to or fixes an issue, be sure to add `refs #XXX` or `fixes #XXX` to the PR description. Replacing `XXX` with the respective issue number. See more about [Linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
- Be sure to fill the PR Template accordingly.
Lastly, make sure to keep the branches updated (e.g. click the `Update branch` button on GitHub PR).