## Contribution

This is great that you'd like to contribute to this project. All change requests should go through the steps described below.

## Pull Requests

**Please, make sure you open an issue before starting with a Pull Request, unless it's a typo or a really obvious error.** Pull requests are the best way to propose changes.

## Conventional commits

Our repository follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification. Releases are drafted from merged pull requests with [release-drafter](https://github.com/release-drafter/release-drafter).

Pull requests should have a title that follows the specification, otherwise, merging is blocked. If you are not familiar with the specification simply ask maintainers to modify. You can also use this cheatsheet if you want:

- `fix: ` prefix in the title indicates that PR is a bug fix and PATCH release must be triggered.
- `feat: ` prefix in the title indicates that PR is a feature and MINOR release must be triggered.
- `docs: ` prefix in the title indicates that PR is only related to the documentation and there is no need to trigger release.
- `chore: ` prefix in the title indicates that PR is only related to cleanup in the project and there is no need to trigger release.
- `test: ` prefix in the title indicates that PR is only related to tests and there is no need to trigger release.
- `refactor: ` prefix in the title indicates that PR is only related to refactoring and there is no need to trigger release.

## Development

Requires the [.NET SDK 10.0](https://dotnet.microsoft.com/download). The repository
pins it in `global.json`.

```bash
dotnet build Codai.slnx
dotnet test Codai.slnx
```

CI currently runs one Ubuntu build job using
`dotnet build Codai.slnx --configuration Release -warnaserror`. It does not run tests,
package/install checks, or a Windows matrix; run relevant tests locally. Release Drafter
and its automatic labels, release publishing, and documentation deployment remain separate
workflows. Scheduled Dependabot updates and the CodeQL workflow are disabled.

CI builds with `-warnaserror`, so a change must leave the build warning-free. Style and
analyzer rules are declared in `.editorconfig` and `Directory.Build.props`, not in the
IDE, so the same rules apply locally and on the build server. `dotnet format
Codai.slnx --no-restore` will apply the mechanical ones.

### Documentation

The docs site in `docs/` uses **Nextra** with the docs theme and Next.js static export.
It includes Pagefind full-text search, native MDX components, and system-aware light/dark
appearance. Pages live in `docs/content/` with `title` and `description` frontmatter;
co-located `_meta.js` files declare sidebar order and labels. Requires Node.js 22 or later.
Before pushing a docs change:

```bash
cd docs
npm ci
npm test        # documentation checker regression tests
npm run check   # navigation, frontmatter, MDX links, README routes
npm run build   # exports docs/out, indexes search, checks exported links and assets
npm run dev     # preview at http://localhost:3000/codai/
```

Documentation accents, wordmarks, and favicon use the app's default
`deepskyblue1` (`#00AFFF`) in both light and dark modes.

[docs.yml](.github/workflows/docs.yml) validates and builds documentation on pull requests.
Changes to `docs/`, `README.md`, or the documentation workflow itself trigger validation.
Pushes to `main` and manual workflow runs also upload `docs/out` and deploy it to
https://meysamhadeli.github.io/codai. In repository **Settings > Pages**, select
**GitHub Actions** as the source. No Mintlify account, hosting subscription, or custom
domain is needed. Local changes appear publicly only after they are pushed to `main`
and the deployment succeeds.

`docs/site.config.mjs` defines the `/codai` base path, published URL, and blue branding.
Keep the base path when previewing locally. A custom domain would require updating that
configuration, README links, and GitHub Pages domain settings together.

Register every new page in its directory's `_meta.js`. Use root-relative internal routes
such as `/getting-started/quickstart` with Markdown links or Nextra's `Cards.Card`;
Next.js adds `/codai` automatically. Public asset URLs must include the base path.
Use native `Cards`, `Steps`, and `Callout` from `nextra/components`, not Mintlify tags.
Static export does not support features requiring a server at request time.

Search indexes are generated by `npm run build` and included in the Pages artifact.
Development mode can preview content without an index, but full search validation
requires serving the exported site with `/codai` as its URL prefix.

The docs package overrides `speech-rule-engine`'s pinned XML parser with patched
`@xmldom/xmldom` 0.9.12. Keep this override until the parent dependency adopts a patched
release. Remaining low-severity KaTeX advisories require upstream updates; do not run
`npm audit fix --force`, which currently proposes downgrading Nextra to version 2.

### Live provider tests

Tests that call a real provider are opt-in and never run in CI:

```bash
export API_KEY="your_deepseek_key"
export CODAI_RUN_INTEGRATION=1
dotnet test tests/Codai.Providers.Tests --filter FullyQualifiedName~DeepSeekLiveTests
```

### Conventions

- Fix the design, not the warning. If an analyzer fires, prefer changing the code to
  suppressing the rule; if you must suppress, do it narrowly and say why.
- Every collaborator is an interface, and it lives in an `Abstractions` folder next to
  the code that consumes it.
- Keep provider-specific behaviour inside `src/Codai.Adapters/Providers`. `Codai.Core` must not
  learn about a specific vendor.
- Add tests with the change. Bug fixes should arrive with a test that fails before the
  fix.
- Update `CHANGELOG.md`, `README.md` and the pages under `docs/` when behaviour a user
  can see changes. The detail belongs in `docs/`; `README.md` stays a short landing page
  that links to the published documentation.

### Releases and NuGet

Merged pull requests are grouped into a draft release by
[Release Drafter](.github/release-drafter.yml), which also decides the next version from
labels: `major`, `minor` (added automatically by a `feat:` title) or `patch` (added
automatically by a `fix:` title). Anything unlabelled is a patch.

Publishing the draft is the only manual step. [publish.yml](.github/workflows/publish.yml)
then stamps every package with the release tag, packs each project under `src/`, checks
that the `Codai` tool installs, and pushes to nuget.org. It needs the `NUGET_API_KEY`
repository secret; without it the workflow fails before packing.

The packages produced by a release are:

| Package | Contents |
| --- | --- |
| `Codai` | The terminal app, installed with `dotnet tool install --global Codai` |
| `Codai.Application` | Host-neutral session runtime |
| `Codai.Core` | Domain types and abstractions |
| `Codai.Adapters` | Providers, configuration, MCP, tools, analysis |

## Resources

- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
- [GitHub Help](https://help.github.com)