Skip to content

ci: rework the pull request template after the bug report form #1677

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-accepted gate, 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.md records only the breaking releases
    of the nvx crate, 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 the license/cla check 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 the template query 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?

  1. Start a pull request against dev: the body holds the two sections of the
    current template.
  2. 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.
  3. 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.md holds, 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, as SECURITY.md requires.
  • 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-modified by hand: the template and
    nvx-fix-issue say that the workflow adds it.
  • doc/contribute.md, nvx-fix-issue, and nvx-promote-openvmm-pin name
    the new sections.
  • A focused test pins the template's headings and their order, and fails
    when doc/contribute.md names other sections.

Metadata

Metadata

Labels

area: ciInitial title-keyword triage suggestion

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions