# 1 How a proper patch should look like

This is a brief description how a proper patch for the Xen project should look like. Examples and tooling tips are not part of this document, those can be found in the Xen Wiki.

## 1.1 The patch subject

The first line at the top of the patch should contain a short description of what the patch does, and hints as to what code it touches. This line is used as the Subject line of the mail when sending the patch.

The hint which code is touched is usually in form of an abstract entity (like e.g. `build` for the build system), or a component (like `tools` or `iommu`). Further specification is possible via adding a sub-component with a slash (e.g. `tools/xenstore`):

    <component>: <description>

E.g.:

    xen/arm: increase memory banks number define value
    tools/libxenevtchn: deduplicate xenevtchn_fd()
    MAINTAINERS: update my email address
    build: correct usage comments in Kbuild.include

The description should give a rough hint what is done in the patch.

The subject line should in general not exceed 80 characters. It must be followed by a blank line.

## 1.2 The commit message

The commit message is free text describing why the patch is done and how the goal of the patch is achieved. A good commit message will describe the current situation, the desired goal, and the way this goal is being achieved. Parts of that can be omitted in obvious cases.

In case additional changes are done in the patch (like e.g. cleanups), those should be mentioned.

When referencing other patches (e.g. `similar to patch xy ...`) those patches should be referenced via their commit id (at least 12 digits) and the patch subject, if the very same patch isn’t referenced by the `Fixes:` tag, too:

    Similar to commit 67d01cdb5518 ("x86: infrastructure to allow converting
    certain indirect calls to direct ones") add ...

The following `git config` settings can be used to add a pretty format for outputting the above style in the `git log` or `git show` commands:

        [core]
                abbrev = 12
        [pretty]
                fixes = Fixes: %h (\"%s\")

Lines in the commit message should not exceed 75 characters, except when copying error output directly into the commit message.

## 1.3 Tags

Tags are entries in the form

    Tag: something

In general tags are added in chronological order. So a `Reviewed-by:` tag should be added after the `Signed-off-by:` tag, as the review happened after the patch was written.

Do not split a tag across multiple lines, tags are exempt from the “wrap at 75 columns” rule in order to simplify parsing scripts.

### 1.3.1 Origin:

Xen has inherited some source files from other open source projects. In case a patch modifying such an inherited file is taken from that project (maybe in modified form), the `Origin:` tag specifies the source of the patch:

    Origin: <repository-URL> <commit-id>

E.g.:

    Origin: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git f093b08c47b3

The commit id should be shortened to its first 12 characters.

All tags above the `Origin:` tag are from the original patch (which should all be kept), while tags after `Origin:` are related to the normal Xen patch process as described here.

### 1.3.2 Fixes:

If your patch fixes a bug in a specific commit, e.g. you found an issue using `git bisect`, please use the `Fixes:` tag with the first 12 characters of the commit id, and the one line summary.

    Fixes: <commit-id> ("<patch-subject>")

E.g.:

    Fixes: 67d01cdb5518 ("x86: infrastructure to allow converting certain indirect calls to direct ones")

If git was configured as explained earlier, this can be retrieved using `git log --pretty=fixes` otherwise `git log --abbrev=12 --oneline` will give the proper tag and commit-id.

### 1.3.3 Backport:

A backport tag is an optional tag in the commit message to request a given commit to be backported to the released trees:

    Backport: <version> [# <comment>]

E.g.:

    Backport: 4.9+

It marks a commit for being a candidate for backports to all released trees from 4.9 onward.

The backport requester is expected to specify which currently supported releases need the backport; but encouraged to specify a release as far back as possible which applies. If the requester doesn’t know the oldest affected tree, they are encouraged to append a comment like the following:

    Backport: 4.9+ # maybe older

Maintainers request the Backport tag to be added on commit. Contributors are welcome to mark their patches with the Backport tag when they deem appropriate. Maintainers will request for it to be removed when that is not the case.

Please note that the Backport tag is a request for backport, which will still need to be evaluated by the maintainers. Maintainers might ask the requester to help with the backporting work if it is not trivial.

### 1.3.4 Reported-by:

This optional tag can be used to give credit to someone reporting an issue. It is in the format:

    Reported-by: name <email@domain>

E.g.:

    Reported-by: Jane Doe <jane.doe@example.org>

As the email address will be made public via git, the reporter of an issue should be asked whether he/she is fine with being mentioned in the patch.

### 1.3.5 Suggested-by:

This optional tag can be used to give credit to someone having suggested the solution the patch is implementing. It is in the format:

    Suggested-by: name <email@domain>

E.g.:

    Suggested-by: Jane Doe <jane.doe@example.org>

As the email address will be made public via git, the reporter of an issue should be asked whether he/she is fine with being mentioned in the patch.

### 1.3.6 Requested-by:

This tag is very similar to the `Suggested-by:` tag, but it refers to an explicit request to add the patch. It is in the format:

    Requested-by: name <email@domain>

E.g.:

    Requested-by: Jane Doe <jane.doe@example.org>

### 1.3.7 Signed-off-by:

This mandatory tag specifies the author(s) of a patch (for each author a separate `Signed-off-by:` tag is needed). It is in the format:

    Signed-off-by: name <email@domain>

E.g.:

    Signed-off-by: Jane Doe <jane.doe@example.org>

The author must be a natural person (not a team or just a company) and the `Signed-off-by:` tag must include the real name of the author (no pseudonym).

By signing the patch with her/his name the author explicitly confirms to have made the contribution conforming to the `Developer's Certificate of Origin`:

    Developer's Certificate of Origin 1.1

    By making a contribution to this project, I certify that:

    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or

    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or

    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.

    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.

### 1.3.8 Reviewed-by:

A `Reviewed-by:` tag can only be given by a reviewer of the patch. With responding to a sent patch adding the `Reviewed-by:` tag the reviewer (which can be anybody) confirms to have looked thoroughly at the patch and didn’t find any issue (being it technical, legal or formal ones). If the review is covering only some parts of the patch, those parts can optionally be specified (multiple areas can be either separated by commas, or be covered with multiple `Reviewed-by:` tags). It is in the format:

    Reviewed-by: name <email@domain> [# area[, area]]

E.g.:

    Reviewed-by: Jane Doe <jane.doe@example.org>
    Reviewed-by: Jane Doe <jane.doe@example.org> # xen/x86

In case a patch is being resent an already given `Reviewed-by:` tag can and should be included, if the patch didn’t meaningfully change the portions of the patch covered by the tag, or if the reviewer already made clear it would be fine to make specific changes and no other changes have been made.

### 1.3.9 Acked-by:

Similar to `Reviewed-by:` the `Acked-by:` tag is given by someone having looked at the patch. The `Acked-by:` tag can only be given by a maintainer of the modified code, and it only covers the code the maintainer is responsible for. With the `Acked-by:` tag the maintainer states, that he/she is fine with the changes in principle, but didn’t do a thorough review. The format is:

    Acked-by: name <email@domain> [# area[, area]]

E.g.:

    Acked-by: Jane Doe <jane.doe@example.org>

Including the `Acked-by:` tag in a patch is done under the same rules as for the `Reviewed-by:` tag, with the implied code area the maintainer who gave the `Acked-by:` tag is responsible for (if no area was specified with the tag).

### 1.3.10 Tested-by:

The `Tested-by:` tag is another tag given by someone else. The one giving it confirms to have tested the patch without finding any functional issues. The format is:

    Tested-by: name <email@domain>

E.g.:

    Tested-by: Jane Doe <jane.doe@example.org>

Including the `Tested-by:` tag in a patch is done under the same rules as for the `Reviewed-by:` tag, now limited to the patch not having been modified regarding code logic (having changed only coding style, comments, or message texts is fine).

## 1.4 Patch version history (change log), further comments

When sending revised versions of a patch it is good practice to include a change log after a line containing only `---` (this line will result in the following text not being included in the commit message). This change log will help reviewers to spot which parts of the patch have changed. Attributing changes due to reviewer comments will help the reviewer even more, e.g.:

    ---
    Changes in v2:
    - changed function foo() as requested by Jane Doe
    - code style fixed

In some cases it might be desirable to add some more information for readers of the patch, like potential enhancements, other possible solutions, etc., which should not be part of the commit message. This information can be added after the `---` line, too.

## 1.5 Recipients of the patch

A patch should always be sent to the xen-devel mailing list xen-devel@lists.xenproject.org and all maintainers and designated reviewers of all touched code areas should get a copy of the mail via Cc. In case some other recipients are known to be interested in the patch, they can be added via Cc, too.