This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project wmaker-crm.git.
The branch, next has been updated
via 385dbdb3d61d55bf4cbdf1e2926456da9e7b6e7f (commit)
via 8b049dec73973f39735d512c270837cab69541f3 (commit)
from 0f26c43371e5e7af43c99ecd941d6624b30ff9a7 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://repo.or.cz/w/wmaker-crm.git/commit/385dbdb3d61d55bf4cbdf1e2926456da9e7b6e7f
commit 385dbdb3d61d55bf4cbdf1e2926456da9e7b6e7f
Author: Carlos R. Mafra <[email protected]>
Date: Sat Jan 14 15:18:32 2012 +0000
Steal documentation with tips on email clients
Applying patches without needing to fix them first helps me save time,
and this file (stolen from the linux kernel documentation) contains some
valuable tips to configure email clients to not mangle the patches you send.
The goal is that patches are sent in the body of the email (to ease review)
and be applied directly with 'git am'.
I personally use mutt as mail client and xjed as an editor. I insert the
patch
in the body of the email using xjed's "Insert file" menu operation. That
works fine, but this documentation file helps you with more choices.
diff --git a/email-clients.txt b/email-clients.txt
new file mode 100644
index 0000000..860c29a
--- /dev/null
+++ b/email-clients.txt
@@ -0,0 +1,237 @@
+Email clients info for Linux
+======================================================================
+
+General Preferences
+----------------------------------------------------------------------
+Patches for the Linux kernel are submitted via email, preferably as
+inline text in the body of the email. Some maintainers accept
+attachments, but then the attachments should have content-type
+"text/plain". However, attachments are generally frowned upon because
+it makes quoting portions of the patch more difficult in the patch
+review process.
+
+Email clients that are used for Linux kernel patches should send the
+patch text untouched. For example, they should not modify or delete tabs
+or spaces, even at the beginning or end of lines.
+
+Don't send patches with "format=flowed". This can cause unexpected
+and unwanted line breaks.
+
+Don't let your email client do automatic word wrapping for you.
+This can also corrupt your patch.
+
+Email clients should not modify the character set encoding of the text.
+Emailed patches should be in ASCII or UTF-8 encoding only.
+If you configure your email client to send emails with UTF-8 encoding,
+you avoid some possible charset problems.
+
+Email clients should generate and maintain References: or In-Reply-To:
+headers so that mail threading is not broken.
+
+Copy-and-paste (or cut-and-paste) usually does not work for patches
+because tabs are converted to spaces. Using xclipboard, xclip, and/or
+xcutsel may work, but it's best to test this for yourself or just avoid
+copy-and-paste.
+
+Don't use PGP/GPG signatures in mail that contains patches.
+This breaks many scripts that read and apply the patches.
+(This should be fixable.)
+
+It's a good idea to send a patch to yourself, save the received message,
+and successfully apply it with 'patch' before sending patches to Linux
+mailing lists.
+
+
+Some email client (MUA) hints
+----------------------------------------------------------------------
+Here are some specific MUA configuration hints for editing and sending
+patches for the Linux kernel. These are not meant to be complete
+software package configuration summaries.
+
+Legend:
+TUI = text-based user interface
+GUI = graphical user interface
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Alpine (TUI)
+
+Config options:
+In the "Sending Preferences" section:
+
+- "Do Not Send Flowed Text" must be enabled
+- "Strip Whitespace Before Sending" must be disabled
+
+When composing the message, the cursor should be placed where the patch
+should appear, and then pressing CTRL-R let you specify the patch file
+to insert into the message.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Evolution (GUI)
+
+Some people use this successfully for patches.
+
+When composing mail select: Preformat
+ from Format->Heading->Preformatted (Ctrl-7)
+ or the toolbar
+
+Then use:
+ Insert->Text File... (Alt-n x)
+to insert the patch.
+
+You can also "diff -Nru old.c new.c | xclip", select Preformat, then
+paste with the middle button.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Kmail (GUI)
+
+Some people use Kmail successfully for patches.
+
+The default setting of not composing in HTML is appropriate; do not
+enable it.
+
+When composing an email, under options, uncheck "word wrap". The only
+disadvantage is any text you type in the email will not be word-wrapped
+so you will have to manually word wrap text before the patch. The easiest
+way around this is to compose your email with word wrap enabled, then save
+it as a draft. Once you pull it up again from your drafts it is now hard
+word-wrapped and you can uncheck "word wrap" without losing the existing
+wrapping.
+
+At the bottom of your email, put the commonly-used patch delimiter before
+inserting your patch: three hyphens (---).
+
+Then from the "Message" menu item, select insert file and choose your patch.
+As an added bonus you can customise the message creation toolbar menu
+and put the "insert file" icon there.
+
+Make the the composer window wide enough so that no lines wrap. As of
+KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending
+the email if the lines wrap in the composer window. Having word wrapping
+disabled in the Options menu isn't enough. Thus, if your patch has very
+long lines, you must make the composer window very wide before sending
+the email. See: https://bugs.kde.org/show_bug.cgi?id=174034
+
+You can safely GPG sign attachments, but inlined text is preferred for
+patches so do not GPG sign them. Signing patches that have been inserted
+as inlined text will make them tricky to extract from their 7-bit encoding.
+
+If you absolutely must send patches as attachments instead of inlining
+them as text, right click on the attachment and select properties, and
+highlight "Suggest automatic display" to make the attachment inlined to
+make it more viewable.
+
+When saving patches that are sent as inlined text, select the email that
+contains the patch from the message list pane, right click and select
+"save as". You can use the whole email unmodified as a patch if it was
+properly composed. There is no option currently to save the email when you
+are actually viewing it in its own window -- there has been a request filed
+at kmail's bugzilla and hopefully this will be addressed. Emails are saved
+as read-write for user only so you will have to chmod them to make them
+group and world readable if you copy them elsewhere.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Lotus Notes (GUI)
+
+Run away from it.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Mutt (TUI)
+
+Plenty of Linux developers use mutt, so it must work pretty well.
+
+Mutt doesn't come with an editor, so whatever editor you use should be
+used in a way that there are no automatic linebreaks. Most editors have
+an "insert file" option that inserts the contents of a file unaltered.
+
+To use 'vim' with mutt:
+ set editor="vi"
+
+ If using xclip, type the command
+ :set paste
+ before middle button or shift-insert or use
+ :r filename
+
+if you want to include the patch inline.
+(a)ttach works fine without "set paste".
+
+Config options:
+It should work with default settings.
+However, it's a good idea to set the "send_charset" to:
+ set send_charset="us-ascii:utf-8"
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Pine (TUI)
+
+Pine has had some whitespace truncation issues in the past, but these
+should all be fixed now.
+
+Use alpine (pine's successor) if you can.
+
+Config options:
+- quell-flowed-text is needed for recent versions
+- the "no-strip-whitespace-before-send" option is needed
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sylpheed (GUI)
+
+- Works well for inlining text (or using attachments).
+- Allows use of an external editor.
+- Is slow on large folders.
+- Won't do TLS SMTP auth over a non-SSL connection.
+- Has a helpful ruler bar in the compose window.
+- Adding addresses to address book doesn't understand the display name
+ properly.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Thunderbird (GUI)
+
+Thunderbird is an Outlook clone that likes to mangle text, but there are ways
+to coerce it into behaving.
+
+- Allows use of an external editor:
+ The easiest thing to do with Thunderbird and patches is to use an
+ "external editor" extension and then just use your favorite $EDITOR
+ for reading/merging patches into the body text. To do this, download
+ and install the extension, then add a button for it using
+ View->Toolbars->Customize... and finally just click on it when in the
+ Compose dialog.
+
+To beat some sense out of the internal editor, do this:
+
+- Edit your Thunderbird config settings so that it won't use format=flowed.
+ Go to "edit->preferences->advanced->config editor" to bring up the
+ thunderbird's registry editor, and set "mailnews.send_plaintext_flowed" to
+ "false".
+
+- Disable HTML Format: Set "mail.identity.id1.compose_html" to "false".
+
+- Enable "preformat" mode: Set "editor.quotesPreformatted" to "true".
+
+- Enable UTF8: Set "prefs.converted-to-utf8" to "true".
+
+- Install the "toggle wordwrap" extension. Download the file from:
+ https://addons.mozilla.org/thunderbird/addon/2351/
+ Then go to "tools->add ons", select "install" at the bottom of the screen,
+ and browse to where you saved the .xul file. This adds an "Enable
+ Wordwrap" entry under the Options menu of the message composer.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TkRat (GUI)
+
+Works. Use "Insert file..." or external editor.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Gmail (Web GUI)
+
+Does not work for sending patches.
+
+Gmail web client converts tabs to spaces automatically.
+
+At the same time it wraps lines every 78 chars with CRLF style line breaks
+although tab2space problem can be solved with external editor.
+
+Another problem is that Gmail will base64-encode any message that has a
+non-ASCII character. That includes things like European names.
+
+ ###
http://repo.or.cz/w/wmaker-crm.git/commit/8b049dec73973f39735d512c270837cab69541f3
commit 8b049dec73973f39735d512c270837cab69541f3
Author: Carlos R. Mafra <[email protected]>
Date: Sat Jan 14 15:11:21 2012 +0000
Expand the documentation about writing patches
Try to convince other people why having non-trivial patches with empty
commit messages are frowned upon.
diff --git a/The-perfect-Window-Maker-patch.txt
b/The-perfect-Window-Maker-patch.txt
index 30c2ff2..c6bf84b 100644
--- a/The-perfect-Window-Maker-patch.txt
+++ b/The-perfect-Window-Maker-patch.txt
@@ -2,65 +2,131 @@ ____________
Introduction
------------
-This short tutorial is meant to help you help me in the task
-of having a maintainable and bug-free Window Maker.
+These notes are meant to help you in the process of making and submitting
+patches to the git repository of wmaker-crm.
-It assumes you have 'git' correctly installed and you have set
-the most basic configuration options via 'git config' (or by
-editing the $HOME/.gitconfig file yourself). See the end
-of this file for an example .gitconfig (which is the one
-I use).
+It assumes you have 'git' correctly installed and you have set the most
+basic configuration options via 'git config'. See the end of this file
+for an example .gitconfig.
-You should probably by now have already cloned my repository,
-but here is how you can do it just in case:
+To clone the wmaker-crm repository you can do:
-# this is the preferred method (ie faster, native implementation)
git clone git://repo.or.cz/wmaker-crm.git
-# use the http method only if are behind a firewall which blocks git://
-git clone http://repo.or.cz/r/wmaker-crm.git
+__________________________
+Producing a patch with git
+--------------------------
-__________________________________
-How to submit patches the git way
-----------------------------------
+You have the wmaker source and you want to write a patch in order to fix
+a bug or improve something. A possible workflow is the following.
-Suppose you have a working copy of the git repo and you found
-a bug in Window Maker and you know how to fix it. This is
-what you can do to submit your patch in a way which will allow
-me to apply it quickly.
+# Optional: Create a new branch (to be safe in case you screw up)
+git checkout -b fixbug
-# Optional: Create a new branch (just to be safe in case you screw up)
-git checkout -b my-new-branch
+Now you fix the bug...
-Now you edit and save the files to fix the bug...
-
-# Optional: Check what you did, review etc
+# Check what you did, review etc
git diff
# if it looks good, commit your changes
git commit -a
-# git will pop up the editor which you configured in .gitconfig so
-# that you will be able to write a commit log. It will use the 'vi'
-# editor otherwise.
-
-(write a _good_ and succinct commit log, explaining what you fixed etc)
+Git will open the editor set in your .gitconfig and you'll have to write a
+commit message. Writing a good message is as important as the source code
+modifications you've just made! See "Writing the commit log" for advice.
-# Prepare the patch to submit to the mailing-list. This step will create
-# a file named 0001-subject-of-your-patch.patch from the last commit
+# Prepare the patch to submit to the mailing-list.
# (use HEAD~2 if you want patches for the last 2 commits etc)
git format-patch HEAD~1
-After the above steps, you are ready to send the created .patch file
-to the mailing-list: [email protected]
+______________________
+Writing the commit log
+----------------------
+
+You had a motivation to write your patch, you studied the sources and you
+found a way to do what you wanted to do. This whole process takes time and
+other people will not want to invest that time to rediscover what you've
+already found.
+
+So the main reason for the commit message is to explain to other people what
+you did, _why_ and _how_. And you must assume that the person you must explain
+these things to will not be as familiar with the code you just modified as you
+are right after writing the patch -- and that includes yourself in a year or
+so. Be verbose in all the steps below.
+
+The good commit log will start with the reason for writing the patch.
+
+For example, if you use wmaker in some way and you expect that X happens but
+you get Y, you should say that very clearly. Sometimes that's enough for other
+more experienced people to know how to solve your issue. They will be able to
+judge your patch better if they know what you wanted to do -- sometimes there
+can be a better way to fix it.
+
+Then you should explain why the wmaker source leads to Y and not to X.
+
+Technicall stuff can be expected at this point, e.g. "upon doing xyz in
function
+foobar(), wmaker sets the variable foo to 'y' instead of setting it to 'x', and
+that will lead to blabla happening in function foobar_squared()...".
+
+And finally you explain how you fixed it.
+
+"You have to set foo to 'x', because then when the function foobar_squared() is
+called it will do X instead of Y because..."
+
+At this point other people will have a clear understanding of what you did with
+minimal effort. And that leads to better patch reviews.
+
+Furthermore, the above reasons should also tell you that you must not do
+more than one thing in the same patch. Again:
+
+ "Each patch must do one thing and one thing only."
+
+If your patch does too much of unrelated stuff, it makes reviewing a nightmare
+and long-term mantainance much worse (think about a patch which introduces a
+regression in the middle of many other nice improvements, and now you have to
+get rid of the regression without removing the improvements -- 'git revert'
+will not help you here).
+
+If you find yourself having troubles to write what you did in the commit
+message, perhaps you did too much. In this case you should split your patch
+into smaller unrelated pieces and produce a patch series. Unfortunately it's
+more work for you, but it's much better for wmaker.
+
+_____________________________________
+Sending the patch to the mailing list
+-------------------------------------
+
+Send your patches to:
+
[email protected]
+
+Please do not send patches to any individual developer unless you have a very
+good reason to avoid more people being able to comment (and improve) on your
+patches.
+
+Sending the patch _properly_ is not as trivial as you might think. Some mail
+clients convert TABs to spaces or word wrap long lines automatically, which
+will result in your patch being rejected as it will not apply with 'git apply'.
+
+Ideally your patch should contain a very good commit message that explains
+why you wrote the patch in the first place (see "Writing the commit log").
+In this case you can simply send the file(s) created in the 'git format-patch'
+step above as the sole content of your email to the mailing list. All your
+reasons and explanations will be in the commit log, and your email will look
+like:
+
+**********************************
+From: someone@someplace
+Subject: [PATCH] Fix something
+
+The commit message.
-Just send it as-is, and I will be able to apply it with
+The diff itself.
-# this is how I am going to apply your patch
-git am 0001-subject-of-your-patch.patch
+**********************************
-and it will automatically append your commit to the repo, with the
-proper authorship, date, subject, commit log etc.
+Read the file email-clients.txt in the topdir of the wmaker-crm repository
+to be adviced on how to tweak your email client to avoid common pitfalls.
___________________
Example .gitconfig
-----------------------------------------------------------------------
Summary of changes:
The-perfect-Window-Maker-patch.txt | 142 ++++++++++++++++------
email-clients.txt | 237 ++++++++++++++++++++++++++++++++++++
2 files changed, 341 insertions(+), 38 deletions(-)
create mode 100644 email-clients.txt
repo.or.cz automatic notification. Contact project admin [email protected]
if you want to unsubscribe, or site admin [email protected] if you receive
no reply.
--
wmaker-crm.git ("Fork from the last available CVS version of Window Maker")
--
To unsubscribe, send mail to [email protected].
