Skip to content

docs: clarify vouch timing, DCO vs signing, Cargo feature conventions - #2810

Open
politerealism wants to merge 2 commits into
NVIDIA:mainfrom
politerealism:docs/contributing-improvements
Open

docs: clarify vouch timing, DCO vs signing, Cargo feature conventions#2810
politerealism wants to merge 2 commits into
NVIDIA:mainfrom
politerealism:docs/contributing-improvements

Conversation

@politerealism

Copy link
Copy Markdown
Contributor

Summary

  • Strengthen vouch timing guidance: note that auto-closed PRs lose their discussion thread and must be manually reopened, reinforcing the "wait for approval before opening a PR" instruction
  • Clarify DCO vs. cryptographic signing: both are separate requirements with distinct failure modes — --signoff is universal for all contributors, GPG signing is org-member-only for copy-pr-bot mirroring
  • Add Cargo feature conventions section covering the feature vs. build mode distinction, transitive dependency auditing (cargo tree -e features), and the need for CI verification beyond compile-time guards
  • Add PR testing checklist guidance: only mark items complete after actual verification, not as a planned checklist

Related Issue

No issue required: documentation-only clarifications to contributor workflow, derived from observed friction in recent PRs.

Changes

  • CONTRIBUTING.md: four targeted additions to the First-Time Contributors, DCO, Pull Requests, and new Cargo feature conventions sections

Testing

  • mise run pre-commit passes clean
  • No Rust or code changes — Markdown only

Checklist

  • Conventional commit format
  • Signed-off for DCO compliance
  • No secrets or credentials included
  • Scoped to the issue at hand

@copy-pr-bot

copy-pr-bot Bot commented Aug 19, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@rhuss

rhuss commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Thanks for improving the contributor guide, @politerealism ! A few thoughts:

DCO vs. signing clarification: Good catch. The distinction between --signoff and GPG signing trips up new contributors regularly. Spelling it out with the separate failure modes is a good call, I think. The switch from -s to --signoff in the example helps too (but for consistencies sake, maybe also expand -m ?)

Vouch timing warning: The added detail about losing the discussion thread is helpful context. Small wording note: "Wait for approval before opening a PR" could be read as "don't even prepare your code." Something like "Get vouched before opening a PR" might be more precise, since contributors can (and should) prepare their work locally while waiting.

Cargo feature conventions: This section is quite specific to Rust packaging and doesn't match the scope of the rest of CONTRIBUTING.md, which covers project-wide conventions for all contributors (TypeScript, Python, Rust, Go, Helm, docs). The transitive dependency auditing advice (cargo tree -e features) is sound, but it would fit better in a crate-level README or architecture doc where Rust contributors naturally look. Would you be open to keeping the language-neutral improvements and moving the Cargo section to a more targeted location? That said, I'm not sure if we really need this detail. Agents won't read CONTRIBUTING.md on the same level as AGENTS.md or CLAUDE.md, so CONTRIBUTING.md is targeting humans, but for that it should be about the big picture. Agents are good in finding out the details (so maybe add this to the agent-aware docs (there are detailed sections for different languages ?)

wdyt ?

@politerealism

Copy link
Copy Markdown
Contributor Author

Love the recommendations. I will get those changes done

- Strengthen vouch timing guidance: explicitly note that auto-closed PRs
  lose their discussion thread and must be manually reopened
- Clarify DCO vs. cryptographic signing: both are separate requirements
  with separate failure modes; --signoff is universal, GPG signing is
  org-member-only for copy-pr-bot mirroring
- Add Cargo feature conventions section covering feature vs. build mode
  distinction, transitive dependency auditing, and CI verification
- Add PR testing checklist guidance: only mark items complete after
  actual verification, not as a plan

No issue required: documentation-only clarifications to contributor
workflow derived from observed friction in recent PRs.

Signed-off-by: politerealism <burdcat17@gmail.com>
- Expand -m to --message in the DCO commit example for consistency
  with --signoff.
- Rephrase vouch step 5 from "Wait for approval" to "Get vouched"
  to clarify that contributors can prepare code locally while waiting.
- Move Cargo feature conventions out of CONTRIBUTING.md (too
  language-specific for a project-wide guide) into architecture/build.md
  under the existing Build Features section, rewritten in prose style
  to match that document's conventions.

Signed-off-by: politerealism <burdcat17@gmail.com>
@politerealism
politerealism force-pushed the docs/contributing-improvements branch from 7ab64c1 to d671004 Compare August 20, 2026 18:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants