Enhancement proposals

This directory holds lightweight design proposals for the NVIDIA DRA driver.

A proposal is a short markdown document that answers a few high-signal questions before code is written, so reviewers and authors are aligned on scope, user-facing surface, component ownership, upgrade impact, and test plan.

When to file a proposal

A proposal is required if the change:

  • Introduces a new feature gate, or graduates an existing gate to a new stability level.
  • Makes a significant behavioral change to an existing feature.
  • Adds or modifies a user-facing API: CRDs, CRD fields, CLI flags, Helm chart values, ResourceSlice attributes, or the kubelet-plugin checkpoint schema.
  • Adds or modifies an external dependency (DCGM, NVSentinel, virtualization stack, etc.).
  • Depends on a change in upstream Kubernetes, or requires coordination with work that is landing there.
  • Touches the ComputeDomain / IMEX coordination layer in a way that affects multi-node behavior.

A proposal is NOT required for:

  • Bug fixes to existing behavior.
  • Documentation-only changes.
  • Internal refactoring with no observable behavior change.
  • Dependency version bumps with no API impact.
  • Incremental additions under an existing feature gate that don't change the design.

If you're unsure, open an issue describing what you want to do and ask — it's cheap to find out early.

How to file one

  1. Look at existing files in this directory and pick the next unused 4-digit number (e.g., if 0001-foo.md exists, name your file 0002-short-title.md).
  2. Copy NNNN-template.md, rename it, and fill it in. Start with Status: provisional.
  3. Open a PR with the new document. You do not need to open an issue first, but feel free to if you want a quick gut-check on whether a proposal is needed.
  4. Iterate on the PR with maintainers. A proposal is ready to merge when OWNERS from this repo approve — the same review flow as any code PR.
  5. Once implementation lands, bump Status to implemented in a follow-up PR.

Proposals are typically a few hundred lines of markdown, not a novel. Optimize for the reviewer's time: write the summary first, show a concrete user-facing example, and don't dwell on sections that don't apply to your change.

For questions or quick discussion, see the chat venues listed in CONTRIBUTING.md.

Status lifecycle

  • provisional — under discussion; design not yet agreed.
  • implementable — design agreed; ready for implementation.
  • implemented — shipped. Note the release in the document's header table.
  • withdrawn — author or maintainers decided not to proceed. Leave the document in place as a decision record.

Feature gate graduation

If your proposal introduces a feature gate, graduation to the next stability level is evaluated against three criteria. Proposals that do not involve a feature gate can skip this section.

  • Feature completeness — the implementation aligns with the intended design goals.
  • Interoperability — the feature works reliably alongside adjacent features (name the ones you tested against).
  • Stability and soak time — the feature has been exercised in production-like environments for long enough to surface issues.

Constraints and caveats that accompany a feature gate should be captured in release notes, not just in the proposal document.