Re: [PATCH v2] docs: document patch rules
Hi,
On 05/02/2022 11:13, Juergen Gross wrote:
On 04.02.22 20:25, Julien Grall wrote:
Hi,
On 03/02/2022 12:54, Juergen Gross wrote:
+## 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
I was under the impression that commit message should be wrap to 72
characters. This is because tools like "git log" would indent the
commit message by 8 characters.
I took that value from the docs/process/tags.pandoc file.
I also checked Linux documentation and they ask to wrap to 75 characters
as well. Not sure where I got the 72 characters from...
There rest of my comments are NITs so:
Reviewed-by: Julien Grall
Cheers,
--
Julien Grall
Re: [PATCH v2] docs: document patch rules
On 04.02.22 20:25, Julien Grall wrote:
Hi,
On 03/02/2022 12:54, Juergen Gross wrote:
+## 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
I was under the impression that commit message should be wrap to 72
characters. This is because tools like "git log" would indent the commit
message by 8 characters.
I took that value from the docs/process/tags.pandoc file.
BTW, git log is indenting the commit message by 4 characters on my
system.
+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.
This would need to be adjusted depending on the answer above.
+
+### 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:
NIT: Likes you did for Fixes tags, can you make clear that the commit id
should be the first 12 characters? So the line...
Okay.
Juergen
OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key
OpenPGP_signature
Description: OpenPGP digital signature
Re: [PATCH v2] docs: document patch rules
Hi,
On 03/02/2022 12:54, Juergen Gross wrote:
+## 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
I was under the impression that commit message should be wrap to 72
characters. This is because tools like "git log" would indent the commit
message by 8 characters.
+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.
This would need to be adjusted depending on the answer above.
+
+### 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:
NIT: Likes you did for Fixes tags, can you make clear that the commit id
should be the first 12 characters? So the line...
+
+E.g.:
+
+Origin: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
f093b08c47b3
... doesn't get horribly long.
+
+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.
Cheers,
--
Julien Grall
Re: [PATCH v2] docs: document patch rules
On 03.02.2022 13:54, Juergen Gross wrote: > 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
[PATCH v2] docs: document patch rules
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
---
v2:
- expanded commit message (Roger Pau Monné)
- some rewordings (Roger Pau Monné, 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é, Jan Beulich)
Signed-off-by: Juergen Gross
---
docs/process/sending-patches.pandoc | 298
docs/process/tags.pandoc| 55 -
2 files changed, 298 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-patches.pandoc
new file mode 100644
index 00..2091037901
--- /dev/null
+++ b/docs/process/sending-patches.pandoc
@@ -0,0 +1,298 @@
+# 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 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`):
+
+:
+
+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 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.
+
+## 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 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:
+
+E.g.:
+
+Origin: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
f093b08c47b3
+
+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 using
+``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:
+
+
