CONTRIBUTING.md

Rama main · réplica de lectura del repositorio original.

# Contributing to SynaptoMind

Thanks for your interest in contributing! This document explains how to get started.

## Code of Conduct

This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold it.

## How to Contribute

### Reporting Bugs

1. Check [existing issues](https://github.com/zumik3-del/synaptomind/issues) to avoid duplicates.
2. Open a new issue with:
   - Clear title and description
   - Steps to reproduce
   - Expected vs actual behavior
   - Your environment (OS, Bun version, etc.)

### Suggesting Features

Open an issue with the `enhancement` label. Describe the problem you want to solve and your proposed solution.

### Submitting Changes

1. Fork the repo and create a feature branch from `dev`.
2. Make your changes following the code conventions below.
3. Run `bun run test` (canonical) or `bun run test:all` to make sure tests pass.
4. Run `bun run format` to apply the Biome formatting standard (see below). CI checks it with
   `bun run format:check` in a **blocking** step, unlike the advisory lint below.
5. Run `bunx biome check src/ eval/` for lint (advisory, not blocking).
6. Open a pull request `dev` → `main` with a **Conventional Commit title** (see below).
7. PRs are merged with a **merge commit** (never squash) — the PR title becomes the merge-commit subject on `main`.

## Commit Convention

This project uses [Conventional Commits](https://www.conventionalcommits.org/). The PR title (used as the merge-commit subject) must follow this format:

```
<type>(<optional scope>): <description>
```

### Allowed types

| Type | When to use |
|------|-------------|
| `fix` | Bug fix |
| `feat` | New feature |
| `feat!` / `BREAKING CHANGE:` | Breaking change |
| `chore`, `docs`, `refactor`, `test`, `ci`, `build` | Maintenance |

Commit types no longer determine the version. A release is prepared explicitly
with `bash scripts/release.sh <version>` (bumps `package.json`), and CI tags and
publishes it when the version-bump merge lands on `main` (see
[AGENTS.md](AGENTS.md) §6). Types still group the generated GitHub Release notes
into Features / Fixes / Other.

### Examples

- `fix: crash on empty database`
- `feat: add thought clustering`
- `feat!: redesign MCP protocol`
- `chore: update dependencies`
- `docs: add installation guide`

### Invalid

- `Fixed bug` (not imperative mood)
- `✨ Added feature` (emoji, not conventional)
- `update stuff` (no type prefix)

## Code Conventions

- **SOLID, KISS, DRY** — apply where it matters, skip where it doesn't.
- **TypeScript strict** — no `any` unless unavoidable.
- **Functions do one thing**, files are short, names are clear.
- **Tests alongside source** — `.test.ts` suffix, same directory.
- **Formatting** — Biome, configured in `biome.json`: 2-space indent, single quotes, no semicolons,
  no trailing commas, 100-column lines. Apply with `bun run format` (it covers `src/`, `eval/`,
  `scripts/` and `deploy/`); `bun run format:check` is the blocking CI gate.

## Project Structure

```
src/
  api/          HTTP routes (Hono)
  config.ts     Configuration loading
  db/           SQLite schema, migrations, queries
  mcp/          MCP server + tools
  services/     Business logic
```

## Development Setup

```bash
bun install
bun run test                # canonical fast suite (src/)
bun run test:all            # full suite
bun run test:deploy         # deploy shell integration
bun run test:eval           # retrieval quality gates
bunx biome check src/ eval/ # lint (advisory)
bun run format              # apply Biome formatting
bun run format:check        # verify formatting (blocking CI gate)
bun run dev                 # start dev server
```

## Pull Request Guidelines

- Keep PRs focused on a single change.
- Reference related issues (e.g., `closes #12`).
- Describe what changed and why.
- Ensure CI passes before requesting review.