Welcome to the NeMo Guardrails contributing guide. We're excited to have you here and grateful for your contributions. This document provides guidelines and instructions for contributing to this project.
- Getting Started
- Contribution Workflow
- Pull Request Checklist
- Reporting Bugs
- Feature Requests
- Folder Structure
- Coding Style
- Submitting Your Work
- Community and Support
To get started quickly, follow the steps below.
-
Ensure you have Python 3.8+ and Git installed on your system. You can check your Python version by running:
python --version
-
Clone the project repository:
git clone https://github.com/NVIDIA/NeMo-Guardrails.git
-
Navigate to the project directory:
cd nemoguardrails
-
Create a virtual environment to isolate your project's dependencies:
python3 -m venv venv
Replace the second
venv
above with the desired name for your virtual environment directory. -
Activate the virtual environment:
-
On Windows:
venv\Scripts\activate
-
On macOS and Linux:
source venv/bin/activate
-
-
Install the main dependencies:
python -m pip install ".[dev]"
This will install pre-commit, pytest, and other development tools, as well as all optional dependencies.
-
Set up pre-commit hooks:
python -m pre-commit install
This will ensure that the pre-commit checks, including Black, are run before each commit.
This project follows the GitFlow branching model which involves the use of several branch types:
main
: Latest stable release branch.develop
: Development branch for integrating features.feature/...
: Feature branches for new features and non-emergency bug fixes.release/...
: Release branches for the final versions published to PyPI.hotfix/...
: Hotfix branches for emergency bug fixes.
Additionally, we recommend the use of docs/...
documentation branches for contributions that update only the project documentation. You can find a comprehensive guide on using GitFlow here: GitFlow Workflow.
To contribute your work, follow the following process:
- Fork the Repository: Fork the project repository to your GitHub account.
- Clone Your Fork: Clone your fork to your local machine.
- Create a Feature Branch: Create a branch from the
develop
branch. - Develop: Make your changes locally and commit them.
- Push Changes: Push your changes to your GitHub fork.
- Open a Pull Request (PR): Create a PR against the main project's
develop
branch.
Before submitting your Pull Request (PR) on GitHub, please ensure you have completed the following steps. This checklist helps maintain the quality and consistency of the codebase.
-
Documentation:
Ensure that all new code is properly documented. Update the README, API documentation, and any other relevant documentation if your changes introduce new features or change existing functionality.
-
Tests Passing:
Run the project's test suite to make sure all tests pass. Include new tests if you are adding new features or fixing bugs. If applicable, ensure your code is compatible with different Python versions or environments.
-
Changelog Updated:
Update the CHANGELOG.md file with a brief description of your changes, following the existing format. This is important for keeping track of new features, improvements, and bug fixes.
-
Code Style and Quality:
Adhere to the project's coding style guidelines. Keep your code clean and readable.
-
Commit Guidelines:
Follow the commit message guidelines, ensuring clear and descriptive commit messages. Sign your commits as per the Developer Certificate of Origin (DCO) or GPG-sign them for verification.
-
No Merge Conflicts:
Before submitting, rebase your branch onto the latest version of the
develop
branch to ensure your PR can be merged smoothly. -
Self Review:
Self-review your changes and compare them to the contribution guidelines to ensure you haven't missed anything.
By following this checklist, you help streamline the review process and increase the chances of your contribution being merged without significant revisions. Your MR/PR will be reviewed by at least one of the maintainers, who may request changes or further details.
Bugs are tracked as GitHub issues. Create an issue on the repository and clearly describe the issue with as much detail as possible.
Feature requests are welcome. To make a feature request, please open an issue on GitHub and tag it as a feature request. Include any specific requirements and why you think it's a valuable addition.
The project is structured as follows:
.
├── chat-ui
├── docs
├── examples
├── nemoguardrails
├── qa
├── tests
chat-ui
: includes a static build of the Guardrails Chat UI. This UI is forked from https://github.com/mckaywrigley/chatbot-ui and is served by the NeMo Guardrails server. The source code for the Chat UI is not included as part of this repository.docs
: includes the official documentation of the project.examples
: various examples, including guardrails configurations (example bots, using different LLMs and others), notebooks, or Python scripts.nemoguardrails
: the source code for the mainnemoguardrails
package.qa
: a set of scripts the QA team uses.tests
: the automated tests set that runs automatically as part of the CI pipeline.
We follow the Black coding style for this project. To maintain consistent code quality and style, the pre-commit framework is used. This tool automates the process of running various checks, such as linters and formatters, before each commit. It helps catch issues early and ensures all contributions adhere to our coding standards.
-
Install Pre-Commit:
First, you need to install pre-commit on your local machine. It can be installed via pip:
pip install pre-commit
Alternatively, you can use other installation methods as listed in the pre-commit installation guide.
-
Configure Pre-Commit in Your Local Repository:
In the root of the project repository, there should be a
.pre-commit-config.yaml
file which contains the configuration and the hooks we use. Run the following command in the root of the repository to set up the git hook scripts:pre-commit install
-
Running Pre-Commit
Automatic Checks: Once
pre-commit
is installed, the configured hooks will automatically run on each Git commit. If any changes are necessary, the commit will fail, and you'll need to make the suggested changes.Manual Run: You can manually run all hooks against all the files with the following command:
pre-commit run --all-files
For certain features, you can provide documentation in the form of a Jupyter notebook. In addition to the notebook, we also require that you generate a README.md file next to the Jupyter notebook, with the same content. To achieve this, follow the following process:
-
Place the jupyter notebook in a separate sub-folder.
-
Install
nbdoc
:pip install nbdoc
-
Use the
build_notebook_docs.py
script from the root of the project to perform the conversion:python build_notebook_docs.py PATH/TO/SUBFOLDER
We require that all contributions are certified under the terms of the Developer Certificate of Origin (DCO), Version 1.1. This certifies that the contribution is your original work or you have the right to submit it under the same or compatible license. Any public contribution that contains commits that are not signed off will not be accepted.
To simplify the process, we accept GPG-signed commits as fulfilling the requirements of the DCO.
A GPG-signed commit provides cryptographic assurance that the commit was made by the holder of the corresponding private key. By configuring your commits to be signed by GPG, you not only enhance the security of the repository but also implicitly certify that you have the rights to submit the work under the project's license and agree to the DCO terms.
-
Generate a GPG key pair:
If you don't already have a GPG key, you can generate a new GPG key pair by following the instructions here: Generating a new GPG key.
-
Add your GPG key to your GitHub/GitLab account:
After generating your GPG key, add it to your GitHub account by following these steps: Adding a new GPG key to your GitHub account.
-
Configure Git to sign commits:
Tell Git to use your GPG key by default for signing your commits:
git config --global user.signingkey YOUR_GPG_KEY_ID
-
Sign commits:
Sign individual commits using the
-S
flaggit commit -S -m "Your commit message"
Or, enable commit signing by default (recommended):
git config --global commit.gpgsign true
Troubleshooting and Help: If you encounter any issues or need help with setting up commit signing, please refer to the GitHub documentation on signing commits. Feel free to contact the project maintainers if you need further assistance.
To ensure the quality and legality of the code base, all contributors are required to certify the origin of their contributions under the terms of the Developer Certificate of Origin (DCO), Version 1.1:
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
The DCO helps to ensure that contributors have the right to submit their contributions under the project's license, protecting both the contributors and the project. It's a lightweight way to manage contributions legally without requiring a more cumbersome Contributor License Agreement (CLA).
For those who prefer or are unable to use GPG-signed commits, we still accept the traditional "Signed-off-by" line in commit messages. To add this line manually, use the -s' or
--signoff` flag in your commit command:
git commit -s -m "Your commit message"
- A GPG-signed commit will be accepted as a declaration that you agree to the terms of the DCO.
- Alternatively, you can manually add a "Signed-off-by" line to your commit messages to comply with the DCO.
By following these guidelines, you help maintain the integrity and legal compliance of the project.
For general questions or discussion about the project, use the discussions section.
Thank you for contributing to NeMo Guardrails!