Repository navigation
Description
What is this bug about?
The
pull request template
has two sections, What and why and Validation, and keeps the rest of its
guidance in HTML comments. It gives no prompt for what a change leaves out, the
alternatives that it rejected, the environment of each run, or compatibility.
It also has no checklist, and no reminder to redact logs. The guidance for
changed tests and OpenVMM pins sits in a comment after Validation, so each
pull request names those sections differently. The comment also tells authors
to add the tests-modified label, which
test-changes.yml
now adds and removes by itself.
Replace .github/pull_request_template.md with a template that asks the
questions of the
Bug report
form (#1669) for a change, and adds a checklist in the manner of
microsoft/mxc
and other open-source projects. The proposal:
<!--
Title: `area: summary`, or the commit subject of a single-commit pull request
(doc/contribute.md, "Commits and pull requests"). Open a draft until the gates
that cover the change pass (doc/contribute.md, "Draft or Ready").
First line: `Fixes #N` or `Closes #N` when this completes the issue, and
`Part of #N` or `Refs #N` otherwise.
Redact credentials, tokens, host names, and other sensitive content from the
commands and logs that you paste. Never disclose an unfixed vulnerability in a
pull request; report it privately, as SECURITY.md requires.
-->
## What does this pull request change?
<!--
The behavior before and after the change, the components and interfaces that
it touches, and where a reviewer should start. Name what it leaves out and the
limitations that remain.
-->
## Why is this change needed?
<!--
The problem that it solves and its practical impact. For a fix, the root cause
and, when you know it, the change that introduced it. The alternatives that you
rejected, such as a patch that the issue proposes, and why.
-->
## How was this change validated?
<!--
Each check that you ran, with its command and its result, as text rather than
screenshots; `python3 scripts/local_gates.py --base origin/dev --run` runs the
gates that the change selects. For a runtime change, the backend (KVM, MSHV,
or WHP), host OS, host type (bare metal or virtual machine), and guest of each
run. The CI runs that you link, and the gates that you leave to CI, such as
backends that you could not reach.
Checks and results:
Backend, host OS, host type, and guest:
Left to CI:
-->
## Checklist
<!-- Check each item that holds or does not apply. -->
- [ ] Tests cover the new or fixed behavior, in the layout that
`python3 scripts/check_test_layout.py` checks.
- [ ] `python3 scripts/check_test_changes.py --base origin/dev` lists no change
to an existing test, or a **Changes to existing tests** section below
explains each one.
- [ ] The documentation that the change affects is updated, including
`.github/copilot-instructions.md` and the skills when a convention or
workflow changes.
- [ ] A change to the public API of `nvx` updates `nvx-rs/public-api/` with
`python3 scripts/public_api.py --update`.
- [ ] Snapshots, protocols, and on-disk formats stay compatible, or the
description says how the change versions or migrates them.
<!--
Add the sections that apply here.
### Changes to existing tests
Each change that check_test_changes.py lists, and why the test still checks
what it did, or why the behavior changed on purpose. The test-changes workflow
adds the `tests-modified` label.
### OpenVMM pin
When the `openvmm` gitlink moves: the OpenVMM pull request and the exact
pinned SHA, the scope and prerequisites, the equivalence evidence, the roadmap
positions, and the landing order: the OpenVMM pull request lands first, by
fast-forwarding `feature/microvm/dev` to the pinned revision.
A first-time contributor signs the Microsoft Contributor License Agreement
when the `license/cla` check asks.
-->Update what names the template's sections with it: the Pull request body
row of
Commits and pull requests,
step 6 of
nvx-fix-issue,
and step 6 of
nvx-promote-openvmm-pin.
nvx-fix-issue also tells its agent to add the tests-modified label.
A pull request body is Markdown, not a form: GitHub cannot require a section,
and a relative link in the body does not resolve to a repository file. So the
template keeps its guidance in comments and links nothing relative, though
check_markdown_links.py would accept a relative link that is broken in a pull
request. Enforcing the sections in CI is outside this issue.
Why is this bug relevant?
Copilot reviews every push, and a maintainer approves the most recent one, so
the description is the first thing that they read. Merged pull requests already
add the information that the template does not ask for, each under its own
heading:
| Information | Headings in merged pull requests |
|---|---|
| Changes to existing tests | Changes to existing tests (tests-modified) (#1672), Existing-test changes (#1651), Tests modified (#1641, #1642, #1668) |
| What the change leaves out | Not in this change (#1643, #1644, #1645), Known limitation (unchanged) (#1646) |
| Compatibility | No version (#1641, #1642), Compatibility, with no version (#1646) |
| Rejected alternatives | Why this is not the issue's patch (#1641, #1642) |
| OpenVMM pin | The OpenVMM pin (#1643 to #1647), OpenVMM pin (#1641, #1642), Equivalence and Landing order (#1668) |
Agents fill the template through nvx-fix-issue and nvx-promote-openvmm-pin,
so its prompts shape their pull requests directly.
The proposal takes from these sources:
| Source | What the proposal takes |
|---|---|
| NVX Bug report form | The question headings; the reminder to redact sensitive content and report vulnerabilities privately; the backend, host OS, host type, and guest of each run; the change that introduced a regression; text rather than screenshots; guidance, not prefilled answers |
| microsoft/mxc | The checklist, with its documentation and Copilot-instructions items; the CLA note, in a closing comment |
| Firecracker | Separate prompts for the change and its reason; checklist items for tests of new and changed behavior and for documentation |
| Kubernetes | Notes for reviewers, as where a reviewer should start |
| Node.js | Tests for every fix and feature, and documentation where relevant |
The proposal leaves these out:
- mxc's spec and
feature-acceptedgate, Azure DevOps pipeline, and
dependency-feed-check: NVX has no such process. - A pull request type, as mxc's Issue Type or Kubernetes'
/kind: the
linked issue carries GitHub's issue type, and the title carries the area. - A release note or changelog entry for every user-facing change, as in
Kubernetes and Firecracker:CHANGELOG.mdrecords only the breaking releases
of thenvxcrate, and the nightly run publishes the others. - Developer Certificate of Origin sign-offs, as in Firecracker and Node.js: NVX
takes the Microsoft CLA, which thelicense/clacheck enforces. - Emoji headings, as in mxc: plain questions match the Bug report form.
- Several templates under
.github/PULL_REQUEST_TEMPLATE/: GitHub offers them
only through thetemplatequery parameter, so one template keeps the
conditional sections in a comment.
Open question: Kubernetes
and Rust
ask authors to disclose AI usage. Many NVX pull requests come from agents,
whose commits carry a Co-authored-by: Copilot trailer. Should the template
ask too?
How is this bug reproducible?
- Start a pull request against
dev: the body holds the two sections of the
current template. - Observe that it asks neither for what the change leaves out, its rejected
alternatives, the environment of each run, nor compatibility, and has no
checklist or reminder to redact logs. - Compare the headings of openvmm: restore the init components of an XSAVE area as init #1641 to ci: pin GitHub Actions references to full commit SHAs #1672 in the table above: each pull request
names the same information differently.
Actual: The template asks only what changed, why, and how it was validated,
and tells authors to add a label that a workflow manages.
Expected: The template asks the questions above, carries the checklist, and
names the conditional sections, so that pull requests present the same
information under the same headings.
Acceptance criteria
-
.github/pull_request_template.mdholds, in order, What does this pull
request change?, Why is this change needed?, How was this change
validated?, and Checklist, with the conditional sections in a
comment. - The guidance sits in HTML comments, with no prefilled answers, so an
unfilled template renders as empty sections. - The template reminds authors to redact sensitive content and to report
vulnerabilities privately, asSECURITY.mdrequires. - The validation prompt asks for commands with their results, the backend,
host OS, host type, and guest of each run, the CI runs, and the gates left
to CI. - The checklist covers tests, changes to existing tests, documentation, the
public API snapshots, and compatibility, each with the command that checks
it where one exists. - Nothing tells authors to add
tests-modifiedby hand: the template and
nvx-fix-issue say that the workflow adds it. -
doc/contribute.md,nvx-fix-issue, andnvx-promote-openvmm-pinname
the new sections. - A focused test pins the template's headings and their order, and fails
whendoc/contribute.mdnames other sections.
Activity
ci: check that every pull request references an issue
ci: check that every pull request references an issue
ci: check that every pull request references an issue
ci: check that every pull request references an issue
ci: check that every pull request references an issue