From 4e891acf679c0020b61889447f8f412324aeffa9 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 3 Feb 2008 16:55:21 -0800 Subject: Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index de08d094e3..cd80148111 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -112,7 +112,12 @@ lose tabs that way if you are not careful. It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other -e-mail discussions. +e-mail discussions. Use of additional markers after PATCH and +the closing bracket to mark the nature of the patch is also +encouraged. E.g. [PATCH/RFC] is often used when the patch is +not ready to be applied but it is for discussion, [PATCH v2], +[PATCH v3] etc. are often seen when you are sending an update to +what you have previously sent. "git format-patch" command follows the best current practice to format the body of an e-mail message. At the beginning of the -- cgit v1.2.3 From 0b0599402d0e4354c60d192eb926f46577040a29 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 3 Feb 2008 17:00:16 -0800 Subject: Documentation/SubmittingPatches: discuss first then submit This is something I've had in mind for some time. I get enough e-mails as-is, and I suspect the workflow to get list members involved would work better if we get the discussion concluded on the list first before patches hit my tree (even 'next'). Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index cd80148111..7900223735 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -34,9 +34,9 @@ Checklist (and a short version for the impatient): - if your name is not writable in ASCII, make sure that you send off a message in the correct encoding. - send the patch to the list (git@vger.kernel.org) and the - maintainer (gitster@pobox.com). If you use - git-send-email(1), please test it first by sending - email to yourself. + maintainer (gitster@pobox.com) if (and only if) the patch + is ready for inclusion. If you use git-send-email(1), + please test it first by sending email to yourself. Long version: @@ -162,7 +162,8 @@ Note that your maintainer does not necessarily read everything on the git mailing list. If your patch is for discussion first, send it "To:" the mailing list, and optionally "cc:" him. If it is trivially correct or after the list reached a consensus, send -it "To:" the maintainer and optionally "cc:" the list. +it "To:" the maintainer and optionally "cc:" the list for +inclusion. Also note that your maintainer does not actively involve himself in maintaining what are in contrib/ hierarchy. When you send fixes and -- cgit v1.2.3 From c11c3b56818bcaf1acea6cb2a9a68fbca644f968 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 3 Feb 2008 17:02:28 -0800 Subject: Documentation/SubmittingPatches: What's Acked-by and Tested-by? We used to talk about "internal company procedures", but this document is about submitting patches to the git mailing list. More useful information is when to say Acked-by: and Tested-by:. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7900223735..0661293371 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -216,10 +216,18 @@ then you just add a line saying This line can be automatically added by git if you run the git-commit command with the -s option. -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. - +Notice that you can place your own Signed-off-by: line when +forwarding somebody else's patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above). + +Some people also put extra tags at the end. + +"Acked-by:" says that the patch was reviewed by the person who +is more familiar with the issues and the area the patch attempts +to modify. "Tested-by:" says the patch was tested by the person +and found to have the desired effect. ------------------------------------------------ MUA specific hints -- cgit v1.2.3 From a941fb4a43472b7b4419c6f6776749791c4495ef Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 10 Feb 2008 14:09:52 -0800 Subject: Documentation/SubmittingPatches - a suggested patch flow Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0661293371..0e155c936c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -229,6 +229,41 @@ is more familiar with the issues and the area the patch attempts to modify. "Tested-by:" says the patch was tested by the person and found to have the desired effect. +------------------------------------------------ +An ideal patch flow + +Here is an ideal patch flow for this project the current maintainer +suggests to the contributors: + + (0) You come up with an itch. You code it up. + + (1) Send it to the list and cc people who may need to know about + the change. + + The people who may need to know are the ones whose code you + are butchering. These people happen to be the ones who are + most likely to be knowledgeable enough to help you, but + they have no obligation to help you (i.e. you ask for help, + don't demand). "git log -p -- $area_you_are_modifying" would + help you find out who they are. + + (2) You get comments and suggestions for improvements. You may + even get them in a "on top of your change" patch form. + + (3) Polish, refine, and re-send to the list and the people who + spend their time to improve your patch. Go back to step (2). + + (4) The list forms consensus that the last round of your patch is + good. Send it to the list and cc the maintainer. + + (5) A topic branch is created with the patch and is merged to 'next', + and cooked further and eventually graduates to 'master'. + +In any time between the (2)-(3) cycle, the maintainer may pick it up +from the list and queue it to 'pu', in order to make it easier for +people play with it without having to pick up and apply the patch to +their trees themselves. + ------------------------------------------------ MUA specific hints -- cgit v1.2.3