Contributing Guidelines

Welcome to NeMo Guardrails. This guide explains the contribution workflow, local setup, validation commands, and review expectations for this repository.

Coding agents should also read AGENTS.md. AI-assisted public contributions must follow AI_POLICY.md.

Before You Contribute

• Search existing issues and pull requests before opening anything new.
• Use the GitHub issue templates for bugs, feature requests, and documentation issues. Blank issues are disabled.
• Use Discussions for support questions and "How do I...?" questions.
• Do not open a pull request before the related issue has been triaged and assigned to you.

Issues must be opened manually by a human using the GitHub issue templates. AI tools may help draft or refine issue text, but agents must not open issues directly through browser automation, the GitHub API, the gh CLI, or similar tooling. The person opening the issue is responsible for reviewing, editing, and owning the content.

Issues and Proposals

Anyone is welcome to open an issue. Opening an issue does not mean you are committing to implement it; it is fine to report a bug, propose an idea, or share a design concern for someone else to pick up later.

If an issue author is not interested or available to implement the change, another contributor may ask to take it over. Wait for maintainer assignment before opening a PR.

Useful issue comments:

I am opening this for tracking, but I am not planning to implement it.

I would like to work on this.
Proposed approach: <1-3 sentence summary>
Planned validation: <tests/docs/checks>

Is this still being worked on? If not, I would be happy to take it over.
Proposed approach: <1-3 sentence summary>

Refactors are maintainer-led and are not accepted as unsolicited PRs. If you believe a refactor is needed, open a refactor proposal issue and wait for maintainer feedback. Maintainers decide whether the refactor should happen, what plan is acceptable, and who, if anyone, should be assigned to implement it.

For work in progress, experiments, or early ideas, share the branch name and relevant files in the issue instead of opening a premature PR.

Pull Request Requirements

Pull requests must be linked to a triaged issue. The PR author must be assigned to that issue before opening the PR. PRs without a linked issue, or opened by someone who is not assigned to the linked issue, may be closed or redirected without review.

Before opening a PR:

• Fork the repository and create a branch from develop.
• Keep the PR cohesive and reviewable.
• Avoid low-value mechanical PRs such as isolated formatting churn, broad cleanup without a clear user benefit, or typo-only sweeps.
• Use the pull request template and list the tests/checks you ran.
• Use a clear Conventional Commit style PR title, for example fix: ..., feat: ..., docs: ..., test: ..., refactor: ..., perf: ..., style: ..., chore: ..., ci: ..., or revert: .... Use scopes when helpful, for example fix(server): ....
• Do not update CHANGELOG.md or CHANGELOG-Colang.md manually. Changelog entries are generated by the release workflow.

Review Readiness

Automated code review tools such as CodeRabbit and Greptile are part of the pre-review workflow. A PR is ready for maintainer review only after the author has addressed unresolved human and automated review comments.

Automated code review is gated on triage. A new PR opens as status: needs triage (a reopened PR keeps whatever triage label it already has); a maintainer applies status: triaged after confirming the PR is linked to a triaged issue assigned to the contributor. CodeRabbit and Greptile are configured to review only PRs with status: triaged.

Before requesting maintainer review:

• Address every automated code review comment, or reply with a clear reason why no change is needed.
• When an automated review tool supports resolution confirmation, wait for the tool to confirm that the issue is resolved. CodeRabbit may resolve conversations itself; other tools, including Greptile, may require a follow-up comment or rerun.
• Address every human reviewer comment, or reply with a clear reason why no change is needed.
• Do not resolve human reviewer conversations unless you opened the conversation, or the reviewer explicitly asks you to resolve it. Human review conversations should normally be resolved by the reviewer who opened them.

The repository may use a status: ready for maintainer review label for PRs that have completed this author-response step. Do not request or apply that label while human or automated review comments still need author action.

AI-Assisted Contributions

AI-assisted contributions are welcome when they meet the same quality bar as any other contribution. If AI tools helped create or substantially modify a contribution:

• Disclose the tool and extent of assistance in the PR description.
• Review and edit AI-generated text before submitting it.
• Make sure you understand every code change and can explain how it interacts with the surrounding system.
• Do not add AI tools as commit co-authors.

See AI_POLICY.md for the full policy.

Development Setup

NeMo Guardrails supports Python 3.10 through 3.13. Install Git, Poetry >=1.8,<2.0, and the compiler/dev tools needed to build Annoy on your platform.

Clone the repository and install development dependencies:

git clone https://github.com/NVIDIA-NeMo/Guardrails.git nemoguardrails
cd nemoguardrails
poetry install --with dev

Install documentation dependencies when working on docs:

poetry install --with dev,docs

Valid optional extras are sdd, eval, gcp, tracing, jailbreak, multilingual, server, chat-ui, and all. For example:

poetry install --with dev -E server -E tracing

For temporary local investigation tools, use the Poetry-managed environment without modifying project dependencies:

poetry run pip install <package-name>

Do not commit environment-only dependency changes.

Validation

Run Python commands through Poetry.

Task	Command
Focused tests	make test TEST=path/to/test_file.py::test_name
Full test suite	make test
Supported Python versions	poetry run tox
Pre-commit hooks	poetry run pre-commit run --all-files
Docs check	make docs-fern
Package coverage	make test-coverage

Run the smallest meaningful test set first, then broaden validation when the change touches shared runtime behavior, public APIs, packaging, server behavior, tracing, or docs.

Set up local pre-commit hooks if you want checks to run before every commit:

poetry run pre-commit install

The pre-commit configuration runs Ruff, Ruff format, license-header insertion, and Pyright.

Documentation and Notebooks

Update documentation when changing user-visible behavior, public APIs, configuration syntax, examples, or installation requirements.

Documentation lives in docs/ as MDX and is built with Fern. Edit the .mdx files directly and check changes with make docs-fern (make docs-fern-live serves locally; make docs-check-links validates links). The Fern CLI version is pinned in fern/fern.config.json; do not run fern upgrade as part of normal documentation changes.

For notebook documentation, place the notebook in its own folder and generate a matching README.md with:

poetry run python build_notebook_docs.py PATH/TO/SUBFOLDER

Important: build_notebook_docs.py currently runs broad git staging and pre-commit commands. Use a clean worktree before running it. Coding agents should not run it unless explicitly asked.

Commit Signing

Public contributions must satisfy the Developer Certificate of Origin (DCO). Use one of these options:

• Submit GPG-signed commits.
• Add a Signed-off-by line to commit messages.

PR titles and commit messages should follow the project commit convention described above. A GPG-signed commit is accepted as a declaration that you agree to the DCO terms. For details, see the Developer Certificate of Origin and GitHub's signing commits documentation.

Community and Support

For general questions and discussion, use GitHub Discussions.