1# How a proper patch should look like 2 3This is a brief description how a proper patch for the Xen project should 4look like. Examples and tooling tips are not part of this document, those 5can be found in the 6[Xen Wiki](https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches). 7 8## The patch subject 9 10The first line at the top of the patch should contain a short description of 11what the patch does, and hints as to what code it touches. This line is used 12as the **Subject** line of the mail when sending the patch. 13 14The hint which code is touched is usually in form of an abstract entity 15(like e.g. `build` for the build system), or a component (like `tools` or 16`iommu`). Further specification is possible via adding a sub-component with 17a slash (e.g. `tools/xenstore`): 18 19 <component>: <description> 20 21E.g.: 22 23 xen/arm: increase memory banks number define value 24 tools/libxenevtchn: deduplicate xenevtchn_fd() 25 MAINTAINERS: update my email address 26 build: correct usage comments in Kbuild.include 27 28The description should give a rough hint *what* is done in the patch. 29 30The subject line should in general not exceed 80 characters. It must be 31followed by a blank line. 32 33## The commit message 34 35The commit message is free text describing *why* the patch is done and 36*how* the goal of the patch is achieved. A good commit message will describe 37the current situation, the desired goal, and the way this goal is being 38achieved. Parts of that can be omitted in obvious cases. 39 40In case additional changes are done in the patch (like e.g. cleanups), those 41should be mentioned. 42 43When referencing other patches (e.g. `similar to patch xy ...`) those 44patches should be referenced via their commit id (at least 12 digits) 45and the patch subject, if the very same patch isn't referenced by the 46`Fixes:` tag, too: 47 48 Similar to commit 67d01cdb5518 ("x86: infrastructure to allow converting 49 certain indirect calls to direct ones") add ... 50 51The following ``git config`` settings can be used to add a pretty format for 52outputting the above style in the ``git log`` or ``git show`` commands: 53 54 [core] 55 abbrev = 12 56 [pretty] 57 fixes = Fixes: %h (\"%s\") 58 59Lines in the commit message should not exceed 75 characters, except when 60copying error output directly into the commit message. 61 62## Tags 63 64Tags are entries in the form 65 66 Tag: something 67 68In general tags are added in chronological order. So a `Reviewed-by:` tag 69should be added **after** the `Signed-off-by:` tag, as the review happened 70after the patch was written. 71 72Do not split a tag across multiple lines, tags are exempt from the 73"wrap at 75 columns" rule in order to simplify parsing scripts. 74 75### Origin: 76 77Xen has inherited some source files from other open source projects. In case 78a patch modifying such an inherited file is taken from that project (maybe in 79modified form), the `Origin:` tag specifies the source of the patch: 80 81 Origin: <repository-URL> <commit-id> 82 83E.g.: 84 85 Origin: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git f093b08c47b3 86 87The commit id should be shortened to its first 12 characters. 88 89All tags **above** the `Origin:` tag are from the original patch (which 90should all be kept), while tags **after** `Origin:` are related to the 91normal Xen patch process as described here. 92 93### Fixes: 94 95If your patch fixes a bug in a specific commit, e.g. you found an issue using 96``git bisect``, please use the `Fixes:` tag with the first 12 characters of 97the commit id, and the one line summary. 98 99 Fixes: <commit-id> ("<patch-subject>") 100 101E.g.: 102 103 Fixes: 67d01cdb5518 ("x86: infrastructure to allow converting certain indirect calls to direct ones") 104 105If git was configured as explained earlier, this can be retrieved using 106``git log --pretty=fixes`` otherwise ``git log --abbrev=12 --oneline`` will 107give the proper tag and commit-id. 108 109### Backport: 110 111A backport tag is an optional tag in the commit message to request a 112given commit to be backported to the released trees: 113 114 Backport: <version> [# <comment>] 115 116E.g.: 117 118 Backport: 4.9+ 119 120It marks a commit for being a candidate for backports to all released 121trees from 4.9 onward. 122 123The backport requester is expected to specify which currently supported 124releases need the backport; but encouraged to specify a release as far 125back as possible which applies. If the requester doesn't know the oldest 126affected tree, they are encouraged to append a comment like the 127following: 128 129 Backport: 4.9+ # maybe older 130 131Maintainers request the Backport tag to be added on commit. Contributors 132are welcome to mark their patches with the Backport tag when they deem 133appropriate. Maintainers will request for it to be removed when that is 134not the case. 135 136Please note that the Backport tag is a **request** for backport, which 137will still need to be evaluated by the maintainers. Maintainers might 138ask the requester to help with the backporting work if it is not 139trivial. 140 141### Reported-by: 142 143This optional tag can be used to give credit to someone reporting an issue. 144It is in the format: 145 146 Reported-by: name <email@domain> 147 148E.g.: 149 150 Reported-by: Jane Doe <jane.doe@example.org> 151 152As the email address will be made public via git, the reporter of an issue 153should be asked whether he/she is fine with being mentioned in the patch. 154 155### Suggested-by: 156 157This optional tag can be used to give credit to someone having suggested the 158solution the patch is implementing. It is in the format: 159 160 Suggested-by: name <email@domain> 161 162E.g.: 163 164 Suggested-by: Jane Doe <jane.doe@example.org> 165 166As the email address will be made public via git, the reporter of an issue 167should be asked whether he/she is fine with being mentioned in the patch. 168 169### Requested-by: 170 171This tag is very similar to the `Suggested-by:` tag, but it refers to an 172explicit request to add the patch. It is in the format: 173 174 Requested-by: name <email@domain> 175 176E.g.: 177 178 Requested-by: Jane Doe <jane.doe@example.org> 179 180### Signed-off-by: 181 182This mandatory tag specifies the author(s) of a patch (for each author a 183separate `Signed-off-by:` tag is needed). It is in the format: 184 185 Signed-off-by: name <email@domain> 186 187E.g.: 188 189 Signed-off-by: Jane Doe <jane.doe@example.org> 190 191The author must be a natural person (not a team or just a company) and the 192`Signed-off-by:` tag must include the real name of the author (no pseudonym). 193 194By signing the patch with her/his name the author explicitly confirms to have 195made the contribution conforming to the `Developer's Certificate of Origin`: 196 197 Developer's Certificate of Origin 1.1 198 199 By making a contribution to this project, I certify that: 200 201 (a) The contribution was created in whole or in part by me and I 202 have the right to submit it under the open source license 203 indicated in the file; or 204 205 (b) The contribution is based upon previous work that, to the best 206 of my knowledge, is covered under an appropriate open source 207 license and I have the right under that license to submit that 208 work with modifications, whether created in whole or in part 209 by me, under the same open source license (unless I am 210 permitted to submit under a different license), as indicated 211 in the file; or 212 213 (c) The contribution was provided directly to me by some other 214 person who certified (a), (b) or (c) and I have not modified 215 it. 216 217 (d) I understand and agree that this project and the contribution 218 are public and that a record of the contribution (including all 219 personal information I submit with it, including my sign-off) is 220 maintained indefinitely and may be redistributed consistent with 221 this project or the open source license(s) involved. 222 223### Reviewed-by: 224 225A `Reviewed-by:` tag can only be given by a reviewer of the patch. With 226responding to a sent patch adding the `Reviewed-by:` tag the reviewer 227(which can be anybody) confirms to have looked thoroughly at the patch and 228didn't find any issue (being it technical, legal or formal ones). If the 229review is covering only some parts of the patch, those parts can optionally 230be specified (multiple areas can be either separated by commas, or be covered 231with multiple `Reviewed-by:` tags). It is in the format: 232 233 Reviewed-by: name <email@domain> [# area[, area]] 234 235E.g.: 236 237 Reviewed-by: Jane Doe <jane.doe@example.org> 238 Reviewed-by: Jane Doe <jane.doe@example.org> # xen/x86 239 240In case a patch is being resent an already given `Reviewed-by:` tag can and 241should be included, if the patch didn't meaningfully change the portions of the 242patch covered by the tag, or if the reviewer already made clear it would be 243fine to make specific changes and no *other* changes have been made. 244 245### Acked-by: 246 247Similar to `Reviewed-by:` the `Acked-by:` tag is given by someone having looked 248at the patch. The `Acked-by:` tag can only be given by a **maintainer** of the 249modified code, and it only covers the code the maintainer is responsible for. 250With the `Acked-by:` tag the maintainer states, that he/she is fine with the 251changes in principle, but didn't do a thorough review. The format is: 252 253 Acked-by: name <email@domain> [# area[, area]] 254 255E.g.: 256 257 Acked-by: Jane Doe <jane.doe@example.org> 258 259Including the `Acked-by:` tag in a patch is done under the same rules as for 260the `Reviewed-by:` tag, with the implied code area the maintainer who gave the 261`Acked-by:` tag is responsible for (if no area was specified with the tag). 262 263### Tested-by: 264 265The `Tested-by:` tag is another tag given by someone else. The one giving it 266confirms to have tested the patch without finding any functional issues. The 267format is: 268 269 Tested-by: name <email@domain> 270 271E.g.: 272 273 Tested-by: Jane Doe <jane.doe@example.org> 274 275Including the `Tested-by:` tag in a patch is done under the same rules as for 276the `Reviewed-by:` tag, now limited to the patch not having been modified 277regarding code logic (having changed only coding style, comments, or message 278texts is fine). 279 280## Patch version history (change log), further comments 281 282When sending revised versions of a patch it is good practice to include a 283change log after a line containing only `---` (this line will result in the 284following text not being included in the commit message). This change log 285will help reviewers to spot which parts of the patch have changed. Attributing 286changes due to reviewer comments will help the reviewer even more, e.g.: 287 288 --- 289 Changes in v2: 290 - changed function foo() as requested by Jane Doe 291 - code style fixed 292 293In some cases it might be desirable to add some more information for readers 294of the patch, like potential enhancements, other possible solutions, etc., 295which should not be part of the commit message. This information can be 296added after the `---` line, too. 297 298## Recipients of the patch 299 300A patch should always be sent **to** the xen-devel mailing list 301<xen-devel@lists.xenproject.org> and all maintainers and designated reviewers 302of all touched code areas should get a copy of the mail via **Cc**. In case 303some other recipients are known to be interested in the patch, they can be 304added via **Cc**, too. 305