# Contributing to the Homeport SDK

Thanks for your interest in contributing. This document covers the local
development setup, branch model, commit conventions, the Developer Certificate
of Origin (DCO) sign-off, how to run the tests, and where to find the RFC
process for substantial changes.

## Development setup

Prerequisites:

- **Node.js 20+**. CI covers Node 20 and 22; `.node-version` sets the local default to Node 22.
- **pnpm 10** (`corepack enable && corepack prepare pnpm@10 --activate`).

Bootstrap the workspace:

```bash
pnpm install
pnpm run validate   # standard local quality gate
pnpm run build      # tsc --project tsconfig.json
pnpm run typecheck  # tsc --noEmit
pnpm run test       # vitest run
```

The `/core` entry point is designed to be dependency-free and runnable in
Node 20+, Bun, Deno, Cloudflare Workers, and modern browsers. Any new runtime
dependency added under `src/core/**` must be reviewed by a maintainer.

## Branch model

- `prod` — deployed/released state. Protected.
- `dev` — integration branch. Protected. PRs target this branch.
- `feat/*`, `fix/*`, `chore/*`, `docs/*` — short-lived feature branches off
  `dev`.

Workflow:

1. Branch off the latest `dev`.
2. Open a PR targeting `dev`.
3. Merge to `dev` after review + green CI. `prod` is updated via release PRs.

If another contributor is already working on a shared branch, pull before
pushing and rebase rather than force-pushing.

## Commit conventions

We use [Conventional Commits](https://www.conventionalcommits.org/) so
`release-please` can generate the changelog and SemVer bumps automatically.

Common types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`,
`build`, `ci`. Breaking changes use `!` after the type or a `BREAKING CHANGE:`
footer. Examples:

```
feat(agents): add list() pagination cursor
fix(retry): handle Retry-After header with HTTP dates
docs: clarify Workers compatibility in README
```

## DCO sign-off (required on every commit)

This project uses the [Developer Certificate of Origin](https://developercertificate.org/)
(DCO) instead of a CLA. Every commit must carry a `Signed-off-by:` trailer
that matches your name and email.

Sign off automatically when you commit:

```bash
git commit -s -m "feat(agents): add list() pagination cursor"
```

The `-s` flag adds a trailer like:

```
Signed-off-by: Jane Doe <jane@example.com>
```

If you forget, amend the last commit with `git commit --amend -s --no-edit`
or rewrite a branch with `git rebase --signoff dev`. The `dco` check on every
PR will block merges that are missing the trailer.

## Running the tests

- `pnpm run test` — full suite (vitest, run-once).
- `pnpm run test:watch` — watch mode during development.
- `pnpm run typecheck` — TypeScript project check, no emit.
- `pnpm run validate` — standard local gate: typecheck, tests, build, docs, and size.
- `pnpm run size` — bundle size check via `size-limit`.

Please add or update tests for any behavior change. PRs that touch runtime
code without corresponding tests will be asked to add them.

## Proposing substantial changes — RFC process

For breaking changes, new public APIs, or anything that meaningfully affects
downstream consumers, follow the RFC process documented in
[GOVERNANCE.md](./GOVERNANCE.md#rfc-process-for-breaking-changes). Small,
additive fixes and internal refactors do not require an RFC.

## Code of Conduct

Participation in this project is governed by our
[Code of Conduct](./CODE_OF_CONDUCT.md). Report violations to
`conduct@nexartis.com`.

## Reporting security issues

Security vulnerabilities follow coordinated disclosure — see
[SECURITY.md](./SECURITY.md). Do not open public issues for suspected
security bugs.

## License

By contributing, you agree that your contributions will be licensed under the
[Apache License, Version 2.0](./LICENSE), and that you have the right to
submit them under that license (as asserted by your DCO sign-off).