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

1. Fork and clone

   Fork the repository on GitHub, then clone your fork locally:

   git clone https://github.com/<your-username>/codegate.git
   cd codegate
   
2. Create a topic branch

   Branch from main. Use a name that reflects the change:

   git checkout -b feat/my-feature
   # or
   git checkout -b fix/issue-description
   

   Keep unrelated changes out of the same branch.

3. Install dependencies

   npm install
   

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

4. Run local verification

   Run all checks before pushing. CI runs the same suite; local failures will block CI.

   npm run lint
   npm run typecheck
   npm run test
   npm run build
   

   All four commands must pass before opening a PR.

5. Commit your changes

   Use Conventional Commit prefixes. These drive automatic versioning via semantic-release.

   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:

   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"
   
6. 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 below.

Commit conventions

CodeGate uses 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 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.