manual: add patch revision and versioning section
PATCH 1/1 manual: add patch revision and versioning section
Improve the contribute manual section by adding an explanation about patch review and version.
The section now provides advices in how to respond mantainers requests and how to proceed on replying them.
--- docs/manual/contribute.txt | 51 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)
docs/manual/contribute.txt +51 -0
@@ -62,6 +62,57 @@ Make sure posted *patches are not line-wrapped*, otherwise they cannot easily be applied. In such a case, fix your e-mail client, or better, use +git send-email+ to send your patches. +Patch revision +^^^^^^^^^^^^^^ + +Hardly ever some revisions will be requested to your patch. Whenever +it happens make sure to always reply in the same thread and include +the changes that have made. + +Revisions must describe which changes they include. When editing your +commit, below the +signed-off-by+ section, add +---+ and your changes. ++git+ will automatically ignore lines below +---+ which will not be merged +on upstream but will be present for reviewers. For longer series, the +changelog should be placed in each commit and the cover letter must contain +a summary of these changes. The following suggested layout example +is not mandatory. + +--------------- +<topic on one line of less than ~80 characters> +<empty newline> +<more paragraphs describing what it is doing and why> +<empty newline> +Signed-off-by John Doe <[email protected]> +--- +Changes v2 -> v3: + - foo bar (Jane) + - bar buz +Changes v1 -> v2: + - alpha bravo (John) + - charly delta +--------------- + +Any patch revision must include the version number. The version number +is simply composed by the letter +v+ followed by an +integer+ greater or +equal 2 (two) (i.e. PATCH v2, PATCH v3 ...). + +This can be easly handle in +git-format-patch+ command by using the option ++--subject-prefix+: + +--------------------- + $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing origin/master +--------------------- + +Mail clients will handle this automatically reply in the same thread but ++git+ won't. Hence the +--in-reply-to+ option in +git-send-email+ must +be used. Get the last +Message-ID+ (it can be found your mail client by +accessing the raw mail). Then use this message id to send your revision +patch: + +--------------------- + $ git send-email --to buildroot at busybox.net --in-reply-to mymsgid at noname.org outgoing/* +--------------------- + Reviewing/Testing patches -------------------------
Signature · 1 line
1.7.9.5
PATCH 1/1 manual: add patch revision and versioning section
Hi Vinicius,
Quoted 7 lines · Vinicius Tinti
Improve the contribute manual section by adding an explanation about patch review and version.
The section now provides advices in how to respond mantainers requests and how to proceed on replying them.
Signed-off-by Vinicius Tinti <[email protected]>
[...]
Quoted 5 lines
+<topic on one line of less than ~80 characters> +<empty newline>
+<more paragraphs describing what it is doing and why> +<empty newline>
+Signed-off-by John Doe <[email protected]>
You missed a colon after "Signed-off-by" like you have in your own sign off above.
baruch
Signature · 3 lines
http://baruch.siach.name/blog/ ~. .~ Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
- baruch at tkos.co.il - tel: +972.2.679.5364, http://www.tkos.co.il -PATCH 1/1 manual: add patch revision and versioning section
In reply to Vinicius TintiHi Vinicius,
2013/3/28 Vinicius Tinti <[email protected]>:
Quoted 55 lines
Improve the contribute manual section by adding an explanation about patch review and version.
The section now provides advices in how to respond mantainers requests and how to proceed on replying them.
Signed-off-by Vinicius Tinti <[email protected]>--- docs/manual/contribute.txt | 51 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)docs/manual/contribute.txt +36
-0@@ -62,6 +62,57 @@ Make sure posted *patches are not line-wrapped*, otherwise they cannot easily be applied. In such a case, fix your e-mail client, or better, use +git send-email+ to send your patches. +Patch revision +^^^^^^^^^^^^^^ + +Hardly ever some revisions will be requested to your patch. Whenever +it happens make sure to always reply in the same thread and include +the changes that have made. + +Revisions must describe which changes they include. When editing your +commit, below the +signed-off-by+ section, add +---+ and your changes. ++git+ will automatically ignore lines below +---+ which will not be merged +on upstream but will be present for reviewers. For longer series, the +changelog should be placed in each commit and the cover letter must contain +a summary of these changes. The following suggested layout example +is not mandatory. + +--------------- +<topic on one line of less than ~80 characters> +<empty newline> +<more paragraphs describing what it is doing and why> +<empty newline> +Signed-off-by John Doe <[email protected]> +--- +Changes v2 -> v3: + - foo bar (Jane) + - bar buz +Changes v1 -> v2: + - alpha bravo (John) + - charly delta +--------------- + +Any patch revision must include the version number. The version number +is simply composed by the letter +v+ followed by an +integer+ greater or +equal 2 (two) (i.e. PATCH v2, PATCH v3 ...). + +This can be easly handle in +git-format-patch+ command by using the option ++--subject-prefix+:
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 110
Quoted 10 lines
docs/manual/contribute.txt +10
-0+ +--------------------- + $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing origin/master +--------------------- + +Mail clients will handle this automatically reply in the same thread but ++git+ won't. Hence the +--in-reply-to+ option in +git-send-email+ must +be used. Get the last +Message-ID+ (it can be found your mail client by +accessing the raw mail). Then use this message id to send your revision +patch:
About the "--in-reply-to" thing (ie. keeping successive revisions of a patch in the same thread), IMHO, it is more a _nice to have_ than a mandatory especially when posting patches one by one, but not easily manageable with pull-requests.
In the latter case (ie. pull-request), it may be good to mark the cover letter "--in-reply-to" the one of the previous submission...
Another thing that hurts me a bit, is the use of "must".
IMHO, it can be understood that any submission that does not meet these requirements will be automatically rejected; I hope we are not so rude ;-) ... but IANA native English speaker, so if no-one else thinks this might be misunderstood, I can live with it. :)
Regards,
Signature · 1 line
Samuel
PATCH 1/1 manual: add patch revision and versioning section
In reply to Vinicius TintiHi Vinicius,
Quoted 23 lines · Vinicius Tinti
Improve the contribute manual section by adding an explanation about patch review and version.
The section now provides advices in how to respond mantainers requests and how
to proceed on replying them.Signed-off-by Vinicius Tinti <[email protected]>--- docs/manual/contribute.txt | 51 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)docs/manual/contribute.txt +0
-0@@ -62,6 +62,57 @@ Make sure posted *patches are not line-wrapped*,otherwise they cannot
easily be applied. In such a case, fix your e-mail client, or better, use +git send-email+ to send your patches.
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 68
Quoted 4 lines
docs/manual/contribute.txt +4
-0+Patch revision +^^^^^^^^^^^^^^ + +Hardly ever some revisions will be requested to your patch. Whenever
The phrase 'hardly ever' means 'almost never'. I think you mean:
Often some revisions will be requested to your patch. or even:
Typically, you will receive review comments on your patch. After discussion, these
comments should be taken into account in a new patch revision.
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 70
Quoted 3 lines
docs/manual/contribute.txt +2
-0+it happens make sure to always reply in the same thread and include +the changes that have made.
Typically one sends a new patch with git format-patch or in my case 'hg email'. Are people actually specifying the original mail identification, or
rephrased: Is this a rule we should try to follow?
Quoted 21 lines
docs/manual/contribute.txt +6
-0+ +Revisions must describe which changes they include. When editing your +commit, below the +signed-off-by+ section, add +---+ and your changes. ++git+ will automatically ignore lines below +---+ which will not be merged +on upstream but will be present for reviewers. For longer series, the +changelog should be placed in each commit and the cover letter mustcontain
docs/manual/contribute.txt +13
-0+a summary of these changes. The following suggested layout example +is not mandatory. + +--------------- +<topic on one line of less than ~80 characters> +<empty newline> +<more paragraphs describing what it is doing and why> +<empty newline> +Signed-off-by John Doe <[email protected]> +--- +Changes v2 -> v3: + - foo bar (Jane) + - bar buz
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 99
Quoted 10 lines
docs/manual/contribute.txt +10
-0+Changes v1 -> v2: + - alpha bravo (John) + - charly delta +--------------- + +Any patch revision must include the version number. The version number +is simply composed by the letter +v+ followed by an +integer+ greater or +equal 2 (two) (i.e. PATCH v2, PATCH v3 ...). + +This can be easly handle in +git-format-patch+ command by using the option
This can be easily handled with the +git-format-patch+ ...
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 110
Quoted 13 lines
++--subject-prefix+:
+
+---------------------
+ $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing origin/master
+---------------------docs/manual/contribute.txt +6
-0+ +Mail clients will handle this automatically reply in the same thread but ++git+ won't. Hence the +--in-reply-to+ option in +git-send-email+ must +be used. Get the last +Message-ID+ (it can be found your mail client by +accessing the raw mail). Then use this message id to send your revision +patch:
I would suggest:
Without extra information, +git+ cannot know to which thread to reply to. However,
you can use the +--in-reply-to+ option to +git-send-email+, which takes the unique
+Message-ID+ of the thread as parameter. This value is present in the mail headers,
which you can view with your mail client using the 'Message source' or similar option.
Then use this message id to send your revised patch:
Quoted 10 lines
+
+---------------------
+ $ git send-email --to buildroot at busybox.net --in-reply-to mymsgid at noname.org outgoing/*
+---------------------
+
Reviewing/Testing patches
-------------------------
Best regards,
Thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20130329/5bba0cb7/attachment.html>