> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to set up a development environment, follow commit conventions, and open a pull request for CodeGate.

Contributions are welcome. This page covers the development workflow, commit conventions, PR requirements, and code of conduct.

## Contribution workflow

<Steps>
  <Step title="Fork and clone">
    Fork the repository on GitHub, then clone your fork locally:

    ```bash theme={null}
    git clone https://github.com/<your-username>/codegate.git
    cd codegate
    ```
  </Step>

  <Step title="Create a topic branch">
    Branch from `main`. Use a name that reflects the change:

    ```bash theme={null}
    git checkout -b feat/my-feature
    # or
    git checkout -b fix/issue-description
    ```

    Keep unrelated changes out of the same branch.
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```

    This also installs the Husky-managed `pre-commit` hook, which runs staged-file linting and formatting automatically before each commit.
  </Step>

  <Step title="Run local verification">
    Run all checks before pushing. CI runs the same suite; local failures will block CI.

    ```bash theme={null}
    npm run lint
    npm run typecheck
    npm run test
    npm run build
    ```

    All four commands must pass before opening a PR.
  </Step>

  <Step title="Commit your changes">
    Use [Conventional Commit](https://www.conventionalcommits.org/) prefixes. These drive automatic versioning via semantic-release.

    ```bash theme={null}
    git commit -m "feat: add workflow audit support for Dependabot"
    git commit -m "fix: correct SARIF output path resolution on Windows"
    git commit -m "docs: update exit code reference"
    ```

    For breaking changes, append `!` to the type or include a `BREAKING CHANGE:` footer:

    ```bash theme={null}
    git commit -m "feat!: remove --legacy-format flag"
    # or
    git commit -m "feat: drop Node 18 support

    BREAKING CHANGE: minimum supported Node version is now 20"
    ```
  </Step>

  <Step title="Open a pull request">
    Push your branch and open a PR against `main`. The PR title must follow the same Conventional Commit format as commits (enforced by the `semantic-pr-title` workflow).

    Your PR should include:

    * A clear problem statement and implementation summary.
    * Test evidence: paste the output of `npm run lint`, `npm run typecheck`, `npm run test`, and `npm run build`.
    * Updated documentation for any user-visible changes.

    See the [PR checklist](#pull-request-checklist) below.
  </Step>
</Steps>

## Commit conventions

CodeGate uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning and changelog generation. Commit types map directly to version bumps:

| Commit type                  | Version bump    | Examples                                   |
| ---------------------------- | --------------- | ------------------------------------------ |
| `feat`                       | Minor (`0.x.0`) | New command, new flag, new output format   |
| `fix`                        | Patch (`0.0.x`) | Bug fix, incorrect behavior correction     |
| `docs`                       | Patch           | Documentation updates                      |
| `refactor`                   | Patch           | Code restructuring without behavior change |
| `perf`                       | Patch           | Performance improvements                   |
| `test`                       | Patch           | Test additions or updates                  |
| `build`                      | Patch           | Build system changes                       |
| `ci`                         | Patch           | CI configuration changes                   |
| `style`                      | Patch           | Code style or formatting                   |
| `chore`                      | Patch           | Maintenance tasks                          |
| `revert`                     | Patch           | Reverts a previous commit                  |
| `feat!` or `BREAKING CHANGE` | Major (`x.0.0`) | Backwards-incompatible changes             |

Keep commits focused. Avoid bundling unrelated changes into one commit.

## PR title requirements

The `semantic-pr-title` workflow validates every PR title against the Conventional Commit format. A PR with an invalid title cannot be merged.

Valid PR title format:

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

Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.

Examples:

```
feat: add --workflow-audits flag to scan command
fix(sarif): correct rule ID format in SARIF output
docs: add exit codes reference page
chore: update semantic-release to v24
feat!: remove support for Node 18
```

## Pull request checklist

Before marking your PR ready for review:

* Tests added or updated for any behavior changes.
* Documentation updated for any user-visible changes.
* CI is green across all matrix entries (Ubuntu, macOS, Windows; Node 20, 22, 24).
* No unrelated changes included in the PR.
* PR title follows Conventional Commit format.

## Reporting security issues

Do not open public issues for vulnerabilities. See [Vulnerability disclosure](/security/vulnerability-disclosure) and follow the private disclosure process.

## Code of conduct

This project is committed to a respectful, harassment-free community.

**Expected behavior:**

* Use welcoming and inclusive language.
* Be respectful of differing viewpoints and experiences.
* Accept constructive feedback gracefully.
* Focus on what is best for the community.

**Unacceptable behavior:**

* Harassment, intimidation, or discrimination.
* Trolling, insulting, or derogatory comments.
* Publishing others' private information without permission.
* Any conduct that is inappropriate in a professional setting.

Project maintainers are responsible for clarifying and enforcing these standards. Report incidents through the contact path in `SUPPORT.md`.