stgit.el: Garbage collect selected patches on reload

[stgit] / Documentation / SubmittingPatches

Checklist (and a short version for the impatient):

        Commits:

        - Make commits of logical units.
        - Check for unnecessary whitespace with "git diff --check"
          before committing.
        - Do not check in commented out code or unneeded files.
        - Provide a meaningful commit message.
        - The first line of the commit message should be a short
          description and should skip the full stop.
        - If you want your work included in StGit, add a
          "Signed-off-by: Your Name <you@example.com>" line to the
          commit message (or just use the option "-s" when
          committing) to confirm that you agree to the Developer's
          Certificate of Origin.
        - Make sure that you have tests for the bug you are fixing.
        - Make sure that the test suite passes after your commit.

        Patch:

        - Preferably use "stg mail" to send patches. The first time,
          it's a good idea to try to mail the patches to yourself to
          see that everything works.
        - Do not PGP sign your patch.
        - Do not attach your patch, but read in the mail.
          body, unless you cannot teach your mailer to
          leave the formatting of the patch alone.
        - Be careful doing cut & paste into your mailer, not to
          corrupt whitespaces.
        - Provide additional information (which is unsuitable for the
          commit message) between the "---" and the diffstat. (The -E
          option to stg mail lets you edit the message before you send
          it out.)
        - If you change, add, or remove a command line option or
          make some other user interface change, the associated
          documentation should be updated as well.
        - 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 (catalin.marinas@gmail.com) if (and only if) the
          patch is ready for inclusion.


Long version:


1. Make separate commits for logically separate changes.

   Unless your patch is really trivial, you should not be sending out
   a patch that was generated between your working tree and your
   commit head. Instead, always make a commit with complete commit
   message and generate a series of patches from your repository. It
   is a good discipline.

   Describe the technical detail of the change(s).

   If your description starts to get too long, that's a sign that you
   probably need to split up your commit to finer grained pieces.

   Oh, another thing. I am picky about whitespaces. Please run git
   diff --check on your changes before you commit.


2. Generate your patch using Git tools out of your commits.

   Git based diff tools (Git, Cogito, and StGit included) generate
   unidiff which is the preferred format.

   You do not have to be afraid to use -M option to "git diff" and
   friends, if your patch involves file renames. The receiving end can
   handle them just fine.

   Please make sure your patch does not include any extra files which
   do not belong in a patch submission. Make sure to review your patch
   after generating it, to ensure accuracy. Before sending out, please
   make sure it cleanly applies to the "master" branch head. If you
   are preparing a work based on some other branch, that is fine, but
   please mark it as such.


3. Sending your patches.

   StGit patches should be sent to the Git mailing list
   (git@vger.kernel.org), and preferably CCed to the StGit maintainer
   (catalin.marinas@gmail.com). The recipients need to be able to read
   and comment on the changes you are submitting. It is important for
   a developer to be able to "quote" your changes, using standard
   e-mail tools, so that they may comment on specific portions of your
   code. For this reason, all patches should be submitted "inline".
   WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do
   not cut-n-paste your patch; you can lose tabs that way if you are
   not careful.

   It is a common convention to prefix your subject line with [StGit
   PATCH]. This lets people easily distinguish patches to StGit from
   other e-mail discussions and patches meant for Git itself. 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.

   "stg mail" command follows the best current practice to format the
   body of an e-mail message. At the beginning of the patch should
   come your commit message, ending with the Signed-off-by: lines, and
   a line that consists of three dashes, followed by the diffstat
   information and the patch itself. If you are forwarding a patch
   from somebody else, optionally, at the beginning of the e-mail
   message just before the commit message starts, you can put a
   "From:" line to name that person.

   You often want to add additional explanation about the patch, other
   than the commit message itself. Place such "cover letter" material
   between the three dash lines and the diffstat. If you have comments
   about a whole series of patches, you can include them in a separate
   cover mail message (the -e option to stg mail).

   Do not attach the patch as a MIME attachment, compressed or not. Do
   not let your e-mail client send quoted-printable. Do not let your
   e-mail client send format=flowed which would destroy whitespaces in
   your patches. Many popular e-mail applications will not always
   transmit a MIME attachment as plain text, making it impossible to
   comment on your code. A MIME attachment also takes a bit more time
   to process. This does not decrease the likelihood of your
   MIME-attached change being accepted, but it makes it more likely
   that it will be postponed.

   Exception: If your mailer is mangling patches then someone may ask
   you to re-send them using MIME, that is OK.

   Do not PGP sign your patch, at least for now. Most likely, your
   maintainer or other people on the list would not have your PGP key
   and would not bother obtaining it anyway. Your patch is not judged
   by who you are; a good patch from an unknown origin has a far
   better chance of being accepted than a patch from a known,
   respected origin that is done poorly or does incorrect things.


4. Sign your work

   To improve tracking of who did what, we've borrowed the "sign-off"
   procedure from the Git and Linux kernel projects on patches that
   are being emailed around. Although StGit is a lot smaller project
   it is a good discipline to follow it.

   The sign-off is a simple line at the end of the explanation for the
   patch, which certifies that you wrote it or otherwise have the
   right to pass it on as a open-source patch. The rules are pretty
   simple: if you can certify the below:

        Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (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

        (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

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not
            modified it.

        (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.

   then you just add a line saying

       Signed-off-by: Random J Developer <random@developer.example.org>

   This line can be automatically added by StGit by any command that
   accepts the --sign option.

   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).

   Also notice that a real name is used in the Signed-off-by: line.
   Please don't hide your real name.

   Some people also put extra tags at the end.

   "Acked-by:" says that the patch was reviewed by a 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

Some of patches I receive or pick up from the list share common
patterns of breakage.  Please make sure your MUA is set up
properly not to corrupt whitespaces.  Here are two common ones
I have seen:

* Empty context lines that do not have _any_ whitespace.

* Non empty context lines that have one extra whitespace at the
  beginning.

One test you could do yourself if your MUA is set up correctly is:

* Send the patch to yourself, exactly the way you would, except
  To: and Cc: lines, which would not contain the list and
  maintainer address.

* Save that patch to a file in UNIX mailbox format.  Call it say
  a.patch.

* Try to apply to the tip of the "master" branch from the
  public repository:

    $ git fetch http://homepage.ntlworld.com/cmarinas/stgit.git master:test-apply
    $ git checkout test-apply
    $ git reset --hard
    $ stg init
    $ stg import -M a.patch

If it does not apply correctly, there can be various reasons.

* Your patch itself does not apply cleanly.  That is _bad_ but
  does not have much to do with your MUA.  Please rebase the
  patch appropriately.

* Your MUA corrupted your patch; "stg import" would complain that
  the patch does not apply.

* Check the imported patch with e.g. "stg show". If it isn't exactly
  what you would want to see in the commit log message, it is very
  likely that the maintainer would end up hand editing the log
  message when he applies your patch. Things like "Hi, this is my
  first patch.\n", if you really want to put in the patch e-mail,
  should come after the three-dash line that signals the end of the
  commit message.


Pine
----

(Johannes Schindelin)

I don't know how many people still use pine, but for those poor
souls it may be good to mention that the quell-flowed-text is
needed for recent versions.

... the "no-strip-whitespace-before-send" option, too. AFAIK it
was introduced in 4.60.

(Linus Torvalds)

And 4.58 needs at least this.

---
diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
Author: Linus Torvalds <torvalds@g5.osdl.org>
Date:   Mon Aug 15 17:23:51 2005 -0700

    Fix pine whitespace-corruption bug

    There's no excuse for unconditionally removing whitespace from
    the pico buffers on close.

diff --git a/pico/pico.c b/pico/pico.c
--- a/pico/pico.c
+++ b/pico/pico.c
@@ -219,7 +219,9 @@ PICO *pm;
            switch(pico_all_done){      /* prepare for/handle final events */
              case COMP_EXIT :          /* already confirmed */
                packheader();
+#if 0
                stripwhitespace();
+#endif
                c |= COMP_EXIT;
                break;


(Daniel Barkalow)

> A patch to SubmittingPatches, MUA specific help section for
> users of Pine 4.63 would be very much appreciated.

Ah, it looks like a recent version changed the default behavior to do the
right thing, and inverted the sense of the configuration option. (Either
that or Gentoo did it.) So you need to set the
"no-strip-whitespace-before-send" option, unless the option you have is
"strip-whitespace-before-send", in which case you should avoid checking
it.


Thunderbird
-----------

(A Large Angry SCM)

Here are some hints on how to successfully submit patches inline using
Thunderbird.

This recipe appears to work with the current [*1*] Thunderbird from Suse.

The following Thunderbird extensions are needed:
        AboutConfig 0.5
                http://aboutconfig.mozdev.org/
        External Editor 0.7.2
                http://globs.org/articles.php?lng=en&pg=8

1) Prepare the patch as a text file using your method of choice.

2) Before opening a compose window, use Edit->Account Settings to
uncheck the "Compose messages in HTML format" setting in the
"Composition & Addressing" panel of the account to be used to send the
patch. [*2*]

3) In the main Thunderbird window, _before_ you open the compose window
for the patch, use Tools->about:config to set the following to the
indicated values:
        mailnews.send_plaintext_flowed  => false
        mailnews.wraplength             => 0

4) Open a compose window and click the external editor icon.

5) In the external editor window, read in the patch file and exit the
editor normally.

6) Back in the compose window: Add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.

7) Optionally, undo the about:config/account settings changes made in
steps 2 & 3.


[Footnotes]
*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
9.3 professional updates.

*2* It may be possible to do this with about:config and the following
settings but I haven't tried, yet.
        mail.html_compose                       => false
        mail.identity.default.compose_html      => false
        mail.identity.id?.compose_html          => false

(Lukas Sandström)

There is a script in contrib/thunderbird-patch-inline which can help
you include patches with Thunderbird in an easy way. To use it, do the
steps above and then use the script as the external editor.

Gnus
----

'|' in the *Summary* buffer can be used to pipe the current
message to an external program, and this is a handy way to drive
"git am".  However, if the message is MIME encoded, what is
piped into the program is the representation you see in your
*Article* buffer after unwrapping MIME.  This is often not what
you would want for two reasons.  It tends to screw up non ASCII
characters (most notably in people's names), and also
whitespaces (fatal in patches).  Running 'C-u g' to display the
message in raw form before using '|' to run the pipe can work
this problem around.


KMail
-----

This should help you to submit patches inline using KMail.

1) Prepare the patch as a text file.

2) Click on New Mail.

3) Go under "Options" in the Composer window and be sure that
"Word wrap" is not set.

4) Use Message -> Insert file... and insert the patch.

5) Back in the compose window: add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.


Gmail
-----

Submitting properly formatted patches via Gmail is simple now that
IMAP support is available. First, edit your ~/.gitconfig to specify your
account settings:

[imap]
        folder = "[Gmail]/Drafts"
        host = imaps://imap.gmail.com
        user = user@gmail.com
        pass = p4ssw0rd
        port = 993
        sslverify = false

Next, ensure that your Gmail settings are correct. In "Settings" the
"Use Unicode (UTF-8) encoding for outgoing messages" should be checked.

Once your commits are ready to send to the mailing list, run the following
command to send the patch emails to your Gmail Drafts folder.

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

Go to your Gmail account, open the Drafts folder, find the patch email, fill
in the To: and CC: fields and send away!