push: mention "git pull" in error message for non-fast forwards

[git.git] / Documentation / SubmittingPatches

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index abc65de9464144a7bac38756c01ab315ab6922eb..eb53e0636e3c3bab06e88ce3371945f5602c5756 100644 (file)
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -41,6 +41,7 @@ Checklist (and a short version for the impatient):
          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.
          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.

+       - see below for instructions specific to your mailer

 
 Long version:
 
 
 Long version:
 


@@ -53,6 +54,34 @@ But the patch submission requirements are a lot more relaxed
 here on the technical/contents front, because the core GIT is
 thousand times smaller ;-).  So here is only the relevant bits.
 
 here on the technical/contents front, because the core GIT is
 thousand times smaller ;-).  So here is only the relevant bits.
 

+(0) Decide what to base your work on.
+
+In general, always base your work on the oldest branch that your
+change is relevant to.
+
+ - A bugfix should be based on 'maint' in general. If the bug is not
+   present in 'maint', base it on 'master'. For a bug that's not yet
+   in 'master', find the topic that introduces the regression, and
+   base your work on the tip of the topic.
+
+ - A new feature should be based on 'master' in general. If the new
+   feature depends on a topic that is in 'pu', but not in 'master',
+   base your work on the tip of that topic.
+
+ - Corrections and enhancements to a topic not yet in 'master' should
+   be based on the tip of that topic. If the topic has not been merged
+   to 'next', it's alright to add a note to squash minor corrections
+   into the series.
+
+ - In the exceptional case that a new feature depends on several topics
+   not in 'master', start working on 'next' or 'pu' privately and send
+   out patches for discussion. Before the final merge, you may have to
+   wait until some of the dependent topics graduate to 'master', and
+   rebase your work.
+
+To find the tip of a topic branch, run "git log --first-parent
+master..pu" and look for the merge commit. The second parent of this
+commit is the tip of the topic branch.

 
 (1) Make separate commits for logically separate changes.
 
 
 (1) Make separate commits for logically separate changes.
 


@@ -170,17 +199,16 @@ patch, format it as "multipart/signed", not a text/plain message
 that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
 not a text/plain, it's something else.
 
 that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
 not a text/plain, it's something else.
 

-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 for
-inclusion.
-
-Also note that your maintainer does not actively involve himself in
-maintaining what are in contrib/ hierarchy.  When you send fixes and
-enhancements to them, do not forget to "cc: " the person who primarily
-worked on that hierarchy in contrib/.
+Unless your patch is a very trivial and an obviously correct one,
+first send it with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the output from
+"git blame $path" and "git shortlog --no-merges $path" would help to
+identify them), to solicit comments and reviews.  After the list
+reached a consensus that it is a good idea to apply the patch, re-send
+it with "To:" set to the maintainer and optionally "cc:" the list for
+inclusion.  Do not forget to add trailers such as "Acked-by:",
+"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
+necessary.

 
 
 (4) Sign your work
 
 
 (4) Sign your work


@@ -519,9 +547,27 @@ Gmail
 
 GMail does not appear to have any way to turn off line wrapping in the web
 interface, so this will mangle any emails that you send.  You can however
 
 GMail does not appear to have any way to turn off line wrapping in the web
 interface, so this will mangle any emails that you send.  You can however

-use any IMAP email client to connect to the google imap server, and forward
+use "git send-email" and send your patches through the GMail SMTP server, or
+use any IMAP email client to connect to the google IMAP server and forward

 the emails through that.
 
 the emails through that.
 

+To use "git send-email" and send your patches through the GMail SMTP server,
+edit ~/.gitconfig to specify your account settings:
+
+[sendemail]
+       smtpencryption = tls
+       smtpserver = smtp.gmail.com
+       smtpuser = user@gmail.com
+       smtppass = p4ssw0rd
+       smtpserverport = 587
+
+Once your commits are ready to be sent to the mailing list, run the
+following commands:
+
+  $ git format-patch --cover-letter -M origin/master -o outgoing/
+  $ edit outgoing/0000-*
+  $ git send-email outgoing/*
+

 To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your
 account settings:
 
 To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your
 account settings:
 


@@ -537,8 +583,7 @@ You might need to instead use: folder = "[Google Mail]/Drafts" if you get an err
 that the "Folder doesn't exist".
 
 Once your commits are ready to be sent to the mailing list, run the
 that the "Folder doesn't exist".
 
 Once your commits are ready to be sent to the mailing list, run the

-following command to send the patch emails to your Gmail Drafts
-folder.
+following commands:

 
   $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
 
 
   $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
 


@@ -546,19 +591,3 @@ Just make sure to disable line wrapping in the email client (GMail web
 interface will line wrap no matter what, so you need to use a real
 IMAP client).
 
 interface will line wrap no matter what, so you need to use a real
 IMAP client).
 

-Alternatively, you can use "git send-email" and send your patches
-through the GMail SMTP server.  edit ~/.gitconfig to specify your
-account settings:
-
-[sendemail]
-       smtpencryption = tls
-       smtpserver = smtp.gmail.com
-       smtpuser = user@gmail.com
-       smtppass = p4ssw0rd
-       smtpserverport = 587
-
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
-
-  $ git format-patch --cover-letter -M origin/master -o outgoing/
-  $ git send-email outgoing/*