From nobody Sun May 19 05:51:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass(p=quarantine dis=none) header.from=suse.com ARC-Seal: i=1; a=rsa-sha256; t=1644304618; cv=none; d=zohomail.com; s=zohoarc; b=evEeN6DGqS4RZ4tDmOy5a2XuA6DNB2CtBL2k7B5ZB2NchyPMy1k2q+le/62RbZX82Zx8hvILfMuWhadPgsR4JGmh+Fw1dO5bc4V5imjfDgLhrnAzb4rCDXytSp2RqzlGS+CnSobY1iORHStLhPwaeK1bpEQyZDvMv2NHFiLy310= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1644304618; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=h1Aps2fmeF2kXxgGc60gFYOcm/Eewiu7EEHlr6uHJUk=; b=LPSkAKLzUNILGQFRA+V8MGbDGxl1OcYchHkgUMtyqj/SVVhNvp4h0FVXcIc1jS6zC9Im6aJkKAJYc0tGXjn2KIQ5/4znvvj6CBAs6WAvrU8c9gYuaRTleW1CLR6HVfOBTWwpJFG4yz6YX0nxKqtWwLJBDhRW1m0AzhWGt1/AEcQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1644304618186821.4605865177633; Mon, 7 Feb 2022 23:16:58 -0800 (PST) Received: from list by lists.xenproject.org with outflank-mailman.267589.461343 (Exim 4.92) (envelope-from ) id 1nHKjo-0004LQ-IK; Tue, 08 Feb 2022 07:16:32 +0000 Received: by outflank-mailman (output) from mailman id 267589.461343; Tue, 08 Feb 2022 07:16:32 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nHKjo-0004LJ-F4; Tue, 08 Feb 2022 07:16:32 +0000 Received: by outflank-mailman (input) for mailman id 267589; Tue, 08 Feb 2022 07:16:30 +0000 Received: from se1-gles-sth1-in.inumbo.com ([159.253.27.254] helo=se1-gles-sth1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nHKjm-0004LD-Hk for xen-devel@lists.xenproject.org; Tue, 08 Feb 2022 07:16:30 +0000 Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) by se1-gles-sth1.inumbo.com (Halon) with ESMTPS id 08945fd5-88af-11ec-8eb8-a37418f5ba1a; Tue, 08 Feb 2022 08:16:28 +0100 (CET) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 680761F37C; Tue, 8 Feb 2022 07:16:28 +0000 (UTC) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id 24FB413483; Tue, 8 Feb 2022 07:16:28 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id rOylB8wYAmLrIQAAMHmgww (envelope-from ); Tue, 08 Feb 2022 07:16:28 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: 08945fd5-88af-11ec-8eb8-a37418f5ba1a DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=susede1; t=1644304588; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=h1Aps2fmeF2kXxgGc60gFYOcm/Eewiu7EEHlr6uHJUk=; b=CocLRIu/V9JZpqquPeYXvGD2g8uE3wBxK+6yZ5qbY+49w4jc7IwgydQex0DkMcTONoDTBU xdNn6xDyxOglkwUPsBYS4t8rcCCqgptpADAlTkhi4rTVI0d0GNLV3iC2+7Fju1mrr8VX+8 nHacG/jYieGP48zSZOjzB0rpHzOyjp0= From: Juergen Gross To: xen-devel@lists.xenproject.org Cc: Juergen Gross , Andrew Cooper , George Dunlap , Jan Beulich , Julien Grall , Stefano Stabellini , Wei Liu , Julien Grall Subject: [PATCH v3] docs: document patch rules Date: Tue, 8 Feb 2022 08:16:26 +0100 Message-Id: <20220208071626.6594-1-jgross@suse.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @suse.com) X-ZM-MESSAGEID: 1644304620546100001 Add a document to describe the rules for sending a proper patch. As it contains all the information already being present in docs/process/tags.pandoc remove that file. The "Reviewed-by:" and "Acked-by:" tags are expanded to allow an optional restriction of the tag. A new tag "Origin:" is added to tag patches taken from another project. Signed-off-by: Juergen Gross Acked-by: Jan Beulich Reviewed-by: Julien Grall --- v3: - add note regarding commit id length for Origin: (Julien Grall) v2: - expanded commit message (Roger Pau Monn=C3=A9) - some rewordings (Roger Pau Monn=C3=A9, Jan Beulich) - add "Requested-by:" description (Jan Beulich) - rename "Taken-from:" to "Origin:" (Jan Beulich) - add reviewers as recipients of patch (Jan Beulich) - style fixes (Roger Pau Monn=C3=A9, Jan Beulich) --- docs/process/sending-patches.pandoc | 300 ++++++++++++++++++++++++++++ docs/process/tags.pandoc | 55 ----- 2 files changed, 300 insertions(+), 55 deletions(-) create mode 100644 docs/process/sending-patches.pandoc delete mode 100644 docs/process/tags.pandoc diff --git a/docs/process/sending-patches.pandoc b/docs/process/sending-pat= ches.pandoc new file mode 100644 index 0000000000..7ff7826c99 --- /dev/null +++ b/docs/process/sending-patches.pandoc @@ -0,0 +1,300 @@ +# 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](https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches= ). + +## 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 us= ed +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`): + + : + +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. + +## 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 descri= be +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), tho= se +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 converti= ng + certain indirect calls to direct ones") add ... + +The following ``git config`` settings can be used to add a pretty format f= or +outputting the above style in the ``git log`` or ``git show`` commands: + + [core] + abbrev =3D 12 + [pretty] + fixes =3D Fixes: %h (\"%s\") + +Lines in the commit message should not exceed 75 characters, except when +copying error output directly into the commit message. + +## 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. + +### Origin: + +Xen has inherited some source files from other open source projects. In ca= se +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: + +E.g.: + + Origin: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.g= it 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. + +### Fixes: + +If your patch fixes a bug in a specific commit, e.g. you found an issue us= ing +``git bisect``, please use the `Fixes:` tag with the first 12 characters of +the commit id, and the one line summary. + + Fixes: ("") + +E.g.: + + Fixes: 67d01cdb5518 ("x86: infrastructure to allow converting certain = indirect calls to direct ones") + +### 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: [# ] + +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. + +### Reported-by: + +This optional tag can be used to give credit to someone reporting an issue. +It is in the format: + + Reported-by: name + +E.g.: + + Reported-by: Jane Doe + +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. + +### Suggested-by: + +This optional tag can be used to give credit to someone having suggested t= he +solution the patch is implementing. It is in the format: + + Suggested-by: name + +E.g.: + + Suggested-by: Jane Doe + +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. + +### 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 + +E.g.: + + Requested-by: Jane Doe + +### 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 + +E.g.: + + Signed-off-by: Jane Doe + +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 pseudony= m). + +By signing the patch with her/his name the author explicitly confirms to h= ave +made the contribution conforming to the `Developer's Certificate of Origin= `: + + Developer's Certificate of Origin 1.1 + =20 + By making a contribution to this project, I certify that: + =20 + (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 + =20 + (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 + =20 + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + =20 + (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. + +### 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 cove= red +with multiple `Reviewed-by:` tags). It is in the format: + + Reviewed-by: name [# area[, area]] + +E.g.: + + Reviewed-by: Jane Doe + Reviewed-by: Jane Doe # 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 o= f 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. + +### Acked-by: + +Similar to `Reviewed-by:` the `Acked-by:` tag is given by someone having l= ooked +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 f= or. +With the `Acked-by:` tag the maintainer states, that he/she is fine with t= he +changes in principle, but didn't do a thorough review. The format is: + + Acked-by: name [# area[, area]] + +E.g.: + + Acked-by: Jane Doe + +Including the `Acked-by:` tag in a patch is done under the same rules as f= or +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). + +### 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. T= he +format is: + + Tested-by: name + +E.g.: + + Tested-by: Jane Doe + +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 messa= ge +texts is fine). + +## 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. Attribu= ting +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 reade= rs +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. + +## Recipients of the patch + +A patch should always be sent **to** the xen-devel mailing list + and all maintainers and designated review= ers +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. diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc deleted file mode 100644 index 1841cb87a8..0000000000 --- a/docs/process/tags.pandoc +++ /dev/null @@ -1,55 +0,0 @@ -Tags: No line splitting ------------------------ -Do not split a tag across multiple lines, tags are exempt from the -"wrap at 75 columns" rule in order to simplify parsing scripts. For -example: - - Fixes: 67d01cdb5518 ("x86: infrastructure to allow converting cert= ain indirect calls to direct ones") - - -Fixes Tag ---------- - -If your patch fixes a bug in a specific commit, e.g. you found an issue us= ing -``git bisect``, please use the 'Fixes:' tag with the first 12 characters of -the SHA-1 ID, and the one line summary. - -The following ``git config`` settings can be used to add a pretty format f= or -outputting the above style in the ``git log`` or ``git show`` commands: - - [core] - abbrev =3D 12 - [pretty] - fixes =3D Fixes: %h (\"%s\") - - -Backport Tag ------------- - -A backport tag is an optional tag in the commit message to request a -given commit to be backported to the released trees: - - 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. - -When possible, please use the Fixes tag instead (or in addition). --=20 2.34.1