> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Crosstalk-Solutions/project-nomad/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to Project N.O.M.A.D. — guidelines, workflow, commit format, and release notes process.

Contributions are welcome and appreciated. Please read this page fully before getting started — it will save you and the maintainers time.

<Note>
  Acceptance of contributions is not guaranteed. All pull requests are evaluated based on quality, relevance, and alignment with the project's goals. The maintainers reserve the right to accept, deny, or modify any pull request at their sole discretion.
</Note>

## Before you start

**Open an issue first.** Before writing any code, [open an issue](https://github.com/Crosstalk-Solutions/project-nomad/issues/new) to discuss your proposed change. This avoids duplicate work and ensures your contribution fits the project's direction.

When opening an issue:

* Use a clear, descriptive title
* Describe the problem you are solving or the feature you want to add
* If it is a bug, include steps to reproduce it and details about your environment
* Redact any personal or sensitive information in logs and configs

## Contribution workflow

<Steps>
  <Step title="Fork the repository">
    Click **Fork** at the top right of the [GitHub repository](https://github.com/Crosstalk-Solutions/project-nomad) to create a copy under your account.

    Then clone your fork and add the upstream remote:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/project-nomad.git
    cd project-nomad
    git remote add upstream https://github.com/Crosstalk-Solutions/project-nomad.git
    ```
  </Step>

  <Step title="Sync with upstream">
    Before starting any new work, sync your fork with the latest upstream changes. Rebase is preferred over merge to keep a clean, linear history:

    ```bash theme={null}
    git fetch upstream
    git checkout main
    git rebase upstream/main
    ```
  </Step>

  <Step title="Create a feature branch">
    Create a new branch with a descriptive name that reflects the purpose of your changes:

    ```bash theme={null}
    git checkout -b fix/issue-123
    # or
    git checkout -b feature/add-new-tool
    ```
  </Step>

  <Step title="Make your changes">
    Implement your changes. Follow the existing code style and conventions. Test your changes locally against a running N.O.M.A.D. instance before submitting.
  </Step>

  <Step title="Add release notes">
    If your changes include anything user-facing, add a summary to the `## Unreleased` section at the top of `admin/docs/release-notes.md`. See [Release Notes format](#release-notes-format) below.
  </Step>

  <Step title="Commit your changes">
    Commit using the [Conventional Commits](#conventional-commits) format. See the format description below.
  </Step>

  <Step title="Submit a pull request">
    Push your branch to your fork and open a pull request against the `main` branch:

    ```bash theme={null}
    git push origin your-branch-name
    ```

    In the PR description:

    * Summarize what your changes do and why
    * Reference the related issue (e.g., `Closes #123`)
    * Note any relevant testing steps or environment details

    Be responsive to feedback. Pull requests with no activity for an extended period may be closed.
  </Step>
</Steps>

## Conventional commits

This project uses [Conventional Commits](https://www.conventionalcommits.org/). All commit messages must follow this format:

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

| Type       | When to use                                |
| ---------- | ------------------------------------------ |
| `feat`     | A new user-facing feature                  |
| `fix`      | A bug fix                                  |
| `docs`     | Documentation changes only                 |
| `refactor` | Code change that is not a fix or feature   |
| `chore`    | Build process, dependency updates, tooling |
| `test`     | Adding or updating tests                   |

The `scope` is optional but encouraged — use it to indicate the area of the codebase affected (e.g., `api`, `ui`, `maps`).

**Examples:**

```bash theme={null}
feat(ui): add dark mode toggle to Command Center
fix(api): resolve container status not updating after restart
docs: update hardware requirements in README
chore(deps): bump docker-compose to v2.24
```

## Release notes format

Human-readable release notes live in `admin/docs/release-notes.md` and are displayed in the Command Center UI.

When your changes include anything user-facing, add an entry to the `## Unreleased` section at the top of that file:

```markdown theme={null}
## Unreleased

### Features
- **Maps**: Added support for downloading South America regional maps

### Bug Fixes
- **AI Chat**: Fixed document upload failing on filenames with special characters
```

Use the format `- **Area**: Description` to stay consistent with existing entries.

Headings to use:

* **Features** — new user-facing capabilities
* **Bug Fixes** — corrections to existing behavior
* **Improvements** — enhancements, refactors, docs, or dependency updates

<Info>
  When a release is triggered, CI automatically stamps the version and date, commits the update, and publishes the content to the GitHub release. You do not need to do this manually.
</Info>

## Versioning

This project uses [Semantic Versioning](https://semver.org/). Versions are managed in the root `package.json` and updated automatically by `semantic-release`. The `project-nomad` Docker image uses this version. The `admin/package.json` version stays at `0.0.0` and should not be changed manually.

## Code of conduct

Please read the full [Code of Conduct](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/CODE_OF_CONDUCT.md) before contributing. In short: be respectful and considerate in all interactions with maintainers and other contributors. Disrespectful or abusive behavior will not be tolerated.