Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (143 loc) · 9.28 KB

CONTRIBUTING.md

File metadata and controls

203 lines (143 loc) · 9.28 KB
Raw

Contributing to NVSentinel

Thank you for your interest in contributing! We welcome contributions from the community.

Getting Started

Before contributing:

  1. Read the README.md to understand the project
  2. Check existing issues to avoid duplicates
  3. Browse discussions for questions
  4. Review the security policy for security-related contributions

How to Contribute

Ways to contribute:

  • 🐛 Report bugs via GitHub issues
  • 💡 Suggest features through feature requests
  • 📝 Improve documentation
  • 🧪 Add tests to increase coverage
  • 🔧 Fix issues with code contributions
  • 💬 Help others in discussions

Reporting Issues

When reporting issues:

  1. Use the issue templates when available
  2. Provide clear reproduction steps
  3. Include environment details (OS, Kubernetes version, etc.)
  4. Add relevant logs or error messages
  5. Search existing issues first to avoid duplicates

Issue Triage and Priority

New issues are labeled needs-triage automatically, and an area/* label is inferred from the issue template and the text of the report. A maintainer for that area then reviews the issue and assigns a priority.

Priority reflects user impact and the cost of leaving the issue unfixed — data loss, incorrect remediation of healthy nodes, and security issues rank highest:

Label Meaning Fix SLA
priority/P0 Critical — data loss, healthy nodes affected, security, or no workaround 30 calendar days
priority/P1 Important — significant impact, workaround exists 183 calendar days
priority/P2 Normal — everything else No fix commitment

Untriaged issues must receive a priority within 7 calendar days. A scheduled workflow checks open issues daily and applies the sla/breached label with a comment when a deadline passes. Issues labeled lifecycle/frozen, blocked, or external-dependency are exempt, since the delay is not something maintainers control.

How to influence priority: add a comment explaining your impact — how many nodes or clusters are affected, whether a workaround exists, and whether it blocks a deployment. Concrete impact is the main input to the decision, and a P2 will be re-prioritized when the evidence justifies it. If an issue looks mis-prioritized, say so on the issue rather than opening a duplicate. For urgent production problems, note that in the issue; for security vulnerabilities, do not use GitHub at all — follow SECURITY.md.

Submitting Pull Requests

For anything beyond a trivial fix (typos, small doc tweaks), open an issue describing the problem or proposal before starting work. This lets maintainers weigh in on approach before you invest time, and avoids duplicate effort.

  1. Fork the repository and create a feature branch
  2. Follow the coding standards and existing patterns
  3. Write or update tests for your changes
  4. Update documentation if needed
  5. Sign your commits (see DCO section below)
  6. Submit a pull request with a clear description, linking the related issue

Pull Request Guidelines:

  • Keep PRs focused on a single issue or feature
  • Write clear, descriptive commit messages (see Commit Message Format below)
  • Include tests for new functionality
  • Ensure all CI checks pass
  • Be responsive to feedback and code review

Commit Message Format:

Commit messages and pull request titles follow Conventional Commits: type(scope): summary, e.g. fix(node-drainer): handle nil taint list. Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. The scope is the affected module or component.

The PR title matters more than it looks: this repository squash-merges, so the title becomes the commit message on main and cannot be corrected afterwards. Nothing in CI enforces the format today, so please get it right before merge.

Review Process:

  • Pull requests are reviewed by the Reviewers/Approvers for the relevant area (see Areas of Ownership in GOVERNANCE.md); see GOVERNANCE.md for the approval requirements by change size.
  • Maintainers aim to give an initial response within 5 business days. If your PR hasn't received feedback after that, feel free to leave a comment on the PR to request a review.
  • Address review feedback with additional commits rather than force-pushing, until the PR is ready to merge, so reviewers can follow the changes.

AI-Assisted Contributions

AI coding assistants are welcome here. This repository ships AGENTS.md specifically to help them produce changes that match our conventions. The policy is about accountability, not tooling.

You are the author. Whatever produced the diff, you are responsible for it. Your DCO sign-off certifies that you have the right to submit the work — that certification is yours, and an AI cannot make it for you.

Understand what you submit. Be able to explain what every line does and why, and answer review questions about it. "The AI wrote it" is not an answer a reviewer can act on. If you do not understand a change well enough to defend it, do not open the PR.

Verify before you submit. Run make lint-test-all and confirm the change actually works. Generated code is confidently wrong in ways that read well: invented API calls, tests that assert nothing, plausible-looking error handling that swallows the error. NVSentinel cordons, drains and reboots nodes in live clusters, so a change that merely looks correct is a real risk to someone's workload.

Do not paste secrets or non-public information into a third-party tool. Cluster configs, logs, kubeconfigs and internal identifiers are easy to include by accident when asking for help.

No attribution trailers. Do not add Co-Authored-By lines or "Generated with ..." markers for AI tools. Disclosing AI assistance in the PR description is welcome when it helps reviewers know where to look closely.

Community Guidelines

  • Be respectful and inclusive in all interactions
  • Follow the Code of Conduct
  • Help maintain a welcoming environment
  • Focus on constructive feedback in reviews

Development Setup

Prerequisites:

  • Go 1.27+ (see .versions.yaml for exact version)
  • Kubernetes cluster (for testing)
  • Docker (for container builds)
  • Make (for build targets)

Quick Setup:

  1. Clone the repository:

    git clone https://github.com/NVIDIA/NVSentinel.git
cd NVSentinel

  2. Install dependencies:

    make dev-env-setup

  3. Run tests:

    make test

  4. Run linting:

    make lint

For detailed development instructions, see DEVELOPMENT.md.

Developer Certificate of Origin

The sign-off is a simple signature at the end of the description for the patch. Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch.

The rules are pretty simple, and sign-off means that you certify the DCO below (from developercertificate.org):

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.

To sign off, you just add the following line to every git commit message:

    Signed-off-by: Joe Smith <joe.smith@email.com>

Note: You must use your real name (sorry, no pseudonyms or anonymous contributions).

Automatic sign-off:

git config user.name "Your Name"
git config user.email "your.email@example.com"
git commit -s  # Automatically adds sign-off

DCO Summary: By signing off, you certify that:

  • (a) You created the contribution and have the right to submit it under the project's open source license
  • (b) The contribution is based on previous work covered by an appropriate license
  • (c) The contribution was provided to you by someone who certified (a) or (b)
  • (d) You understand the contribution is public and will be maintained indefinitely