Patch Submission Reference¶

This page contains detailed reference material for submitting patches to the Xen Project. See Submitting Patches for the quick-start workflow.

Writing commit messages¶

When writing a commit message, think about three audiences:

Reviewers who need to understand what the patch does, whether it is correct, and what side effects it has.
People scanning changelogs who decide whether a patch is relevant for backporting or out-of-tree work.
Future readers who need to understand why the code is the way it is.

The description should answer: what is the situation, why is it a problem, how does this patch fix it, and what else do reviewers need to know?

*-by tags¶

These tags appear in the commit message and carry meaning during and after review.

Reported-by: Name <email>: Credits the person who found the bug the patch fixes. Add this before Signed-off-by.
Tested-by: Name <email>: Indicates the listed person applied the patch and confirmed it works as described.
Acked-by: Name <email>: A maintainer has reviewed the patch and has no objection to it being merged.
Reviewed-by: Name <email>: A community member or designated reviewer has performed a thorough review and considers the patch ready.

When resending a revised patch, carry forward Acked-by and Reviewed-by tags from the previous version — unless you made significant changes to the parts those reviewers looked at.

CC list¶

Always CC the maintainer of the code you are modifying. Maintainers are listed in the MAINTAINERS file at the root of the repository. If no specific maintainer is listed for the area you are modifying, CC the people listed under THE REST.

add_maintainers.pl handles this automatically. If someone reviewed your patch but was not on the original CC list, add them manually to subsequent revisions.

Changelog format¶

When resending a revised patch or series, include a changelog after the --- line. This content appears in the email but is not included in the commit.

For an individual patch:

Signed-off-by: Jane Smith <jane@example.com>

---
CC: maintainer@example.com

Changes in v3:
- Fix off-by-one error in bounds check
- Update commit message to clarify intent

Changes in v2:
- Rewrite using the new helper API

For a patch series, the changelog goes at the end of the cover letter and should be higher-level — focus on pointing reviewers to areas that changed significantly.

Patch series rules¶

Each patch should do one logical thing. Reviewers should be able to understand each step in isolation.
No patch should break existing functionality on its own, even temporarily.
Do not fix a bug introduced by one patch by modifying a later patch — go back and amend the patch that introduced the bug.
Keep cleanup and refactoring patches separate from functional changes. However, style corrections on lines you are already changing are generally accepted.
Mark cleanup patches explicitly as having no functional changes.

Cover letter¶

Every patch series must have a cover letter. The cover letter should explain:

What you are trying to achieve and why it is needed
How the series achieves the goal
Any pre-conditions, assumptions, or dependencies
Links to relevant specifications, design documents, or prior mailing list discussion

The level of detail should match the size and complexity of the series.

Cover letters are not committed to the git tree. If the cover letter contains information that should be preserved long-term, add a document under docs/designs/, docs/features/, or docs/specs/ in the repository as part of the series and reference it from the cover letter.

Providing a git branch¶

For large series, include a link to a public git branch in your cover letter so reviewers can pull it directly. You can fork the Xen Project mirrors and push your branch:

Regular contributors can request personal repository hosting at xenbits by emailing community dot manager at xenproject dot org.

add_maintainers.pl options¶

Beyond the basic -d <patchdir> usage, add_maintainers.pl has options that control where CC lines are placed.

-v N: Use when patches are stored with version numbers generated by --reroll-count=N.
-p commit: Insert CC lines into the patch body so they become part of the commit message.
-p none -c header: Insert CC lines into the cover letter only, without modifying individual patch files. Useful for rerolled series where you do not want to touch the patch bodies.
-t / --tags: Add people who have *-by tags to the email headers.

If you prefer to add CCs manually, run ./scripts/get_maintainer.pl <patchfile> on each patch, copy the output as Cc: lines into the patch file, and repeat for the cover letter using the union of all per-patch results.

Single-patch shortcut¶

For a single patch, you can fold the three workflow steps into one command:

git send-email --to xen-devel@lists.xenproject.org \
    --cc-cmd="./scripts/get_maintainer.pl" -1

This gets the CC list automatically from get_maintainer.pl without needing a separate add_maintainers.pl step.

Patching point releases¶

When working against an older Xen version, your local MAINTAINERS file may be outdated. Use the MAINTAINERS file from the current master branch to ensure the right people are CC’d:

git format-patch ... -o <patchdir> ...
git checkout master
./scripts/add_maintainers.pl -d <patchdir>
git checkout <original-branch>
git send-email ... <patchdir>

After your patch is committed¶

Monitor the osstest flight reports that are sent to xen-devel. If your patch causes test failures, you will be expected to respond promptly to help diagnose and fix the problem. Patches that cannot be fixed quickly may be reverted.

Commits appear first in the staging branch before being propagated to master once tests pass.

QEMU trees¶

Xen uses two QEMU trees:

qemu-xen-traditional — the older stable tree; bug fixes only.
qemu-xen — the development tree, based on the latest upstream QEMU stable branch.

New features must be developed against upstream QEMU first. Once accepted upstream, they can be backported to qemu-xen on request. To request a backport, email xen-devel@lists.xenproject.org with the upstream commit ID and the reason for the backport.