Window Maker 0.95.7
[wmaker-crm.git] / The-perfect-Window-Maker-patch.txt
Commit [+]AuthorDateLineData
781b6633
CM
Carlos R. Mafra2009-10-11 17:14:53 +02001____________
2Introduction
3------------
4
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +00005These notes are meant to help you in the process of making and submitting
6patches to the git repository of wmaker-crm.
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +02007
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +00008It assumes you have 'git' correctly installed and you have set the most
9basic configuration options via 'git config'. See the end of this file
10for an example .gitconfig.
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020011
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +000012To clone the wmaker-crm repository you can do:
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020013
781b6633
CM
Carlos R. Mafra2009-10-11 17:14:53 +020014git clone git://repo.or.cz/wmaker-crm.git
15
fd5c06c0
CC
Christophe CURIS2014-03-02 00:44:15 +010016You should note that the development occur in the #next branch, and
17patches are backported to #master when considered ok. So, you probably
18want to switch to #next branch, if not already done:
19
20git checkout next
21
029846dd
CC
Christophe CURIS2014-07-04 23:28:49 +020022____________________
23Testing your changes
24--------------------
25
26If you want to raise the quality of your contribution, you are strongly
27encouraged to use at least this configure option:
28
29./configure --enable-debug
30
31This does not only enable debugging information, which you may need when
32testing your work, it also enables a number of extra compiler warning
33which help keeping safer code.
34
b2668083
CC
Christophe CURIS2015-01-20 22:03:49 +010035You will probably want also to run this in the end, because it does some
36checks on the source tree:
37
38make check
39
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +000040__________________________
41Producing a patch with git
42--------------------------
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020043
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +000044You have the wmaker source and you want to write a patch in order to fix
0e99f6ea Christophe CURIS2014-03-02 00:44:17 +010045a bug or improve something. A possible work-flow is the following:
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020046
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +000047# Optional: Create a new branch (to be safe in case you screw up)
48git checkout -b fixbug
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020049
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +000050Now you fix the bug...
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020051
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +000052# Check what you did, review etc
781b6633
CM
Carlos R. Mafra2009-10-11 17:14:53 +020053git diff
54
55# if it looks good, commit your changes
56git commit -a
57
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +000058Git will open the editor set in your .gitconfig and you'll have to write a
59commit message. Writing a good message is as important as the source code
60modifications you've just made! See "Writing the commit log" for advice.
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +020061
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +000062# Prepare the patch to submit to the mailing-list.
781b6633
CM
Carlos R. Mafra2009-10-11 17:14:53 +020063# (use HEAD~2 if you want patches for the last 2 commits etc)
64git format-patch HEAD~1
65
fd5c06c0
CC
Christophe CURIS2014-03-02 00:44:15 +010066# If you have created your own branch, and want all your commits created
67# after the #next branch, you can use:
68git format-patch next
69
029846dd
CC
Christophe CURIS2014-07-04 23:28:49 +020070
71In order to ensure consistency in the code, there's an extra step to
72check the patchs. You should run this script (inherited from the Linux
73kernel) on the patch files generated and fix your commits for what it
74reports:
75
76./checkpatch.pl 00*
77
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +000078______________________
79Writing the commit log
80----------------------
81
82You had a motivation to write your patch, you studied the sources and you
83found a way to do what you wanted to do. This whole process takes time and
84other people will not want to invest that time to rediscover what you've
85already found.
86
87So the main reason for the commit message is to explain to other people what
88you did, _why_ and _how_. And you must assume that the person you must explain
89these things to will not be as familiar with the code you just modified as you
90are right after writing the patch -- and that includes yourself in a year or
91so. Be verbose in all the steps below.
92
93The good commit log will start with the reason for writing the patch.
94
95For example, if you use wmaker in some way and you expect that X happens but
96you get Y, you should say that very clearly. Sometimes that's enough for other
97more experienced people to know how to solve your issue. They will be able to
98judge your patch better if they know what you wanted to do -- sometimes there
99can be a better way to fix it.
100
101Then you should explain why the wmaker source leads to Y and not to X.
102
0e99f6ea Christophe CURIS2014-03-02 00:44:17 +0100103Technical stuff can be expected at this point, e.g. "upon doing xyz in function
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +0000104foobar(), wmaker sets the variable foo to 'y' instead of setting it to 'x', and
105that will lead to blabla happening in function foobar_squared()...".
106
107And finally you explain how you fixed it.
108
109"You have to set foo to 'x', because then when the function foobar_squared() is
110called it will do X instead of Y because..."
111
112At this point other people will have a clear understanding of what you did with
113minimal effort. And that leads to better patch reviews.
114
115Furthermore, the above reasons should also tell you that you must not do
116more than one thing in the same patch. Again:
117
118 "Each patch must do one thing and one thing only."
119
120If your patch does too much of unrelated stuff, it makes reviewing a nightmare
0e99f6ea Christophe CURIS2014-03-02 00:44:17 +0100121and long-term maintenance much worse (think about a patch which introduces a
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +0000122regression in the middle of many other nice improvements, and now you have to
123get rid of the regression without removing the improvements -- 'git revert'
124will not help you here).
125
126If you find yourself having troubles to write what you did in the commit
127message, perhaps you did too much. In this case you should split your patch
128into smaller unrelated pieces and produce a patch series. Unfortunately it's
129more work for you, but it's much better for wmaker.
130
131_____________________________________
132Sending the patch to the mailing list
133-------------------------------------
134
135Send your patches to:
136
137wmaker-dev@lists.windowmaker.org
138
139Please do not send patches to any individual developer unless you have a very
140good reason to avoid more people being able to comment (and improve) on your
141patches.
142
fd5c06c0
CC
Christophe CURIS2014-03-02 00:44:15 +0100143The HIGHLY RECOMMENDED way to send a patch is to actually let Git do it for
144you, otherwise you may face the problems below. Doing this is really easy:
145
146# Tell git once how to send mails:
147# (of course, replace smtp.example.com with your ISP's)
148git config --global sendemail.smtpserver "smtp.example.com"
149git config --global sendemail.validate true
150git config sendemail.to "Window Maker Devel <wmaker-dev@lists.windowmaker.org>"
151
152# If you're sending more than 1 patch, you may be interested in having an
153# introduction mail for the batch:
154git format-patch --cover-letter next
155vi/emacs/nedit/whatever 0000-cover-letter.patch
156
157# When you're satisfied, ask Git to mail all the patches:
158git send-email 00*
159
160
161If you do not want or cannot let Git send them for you, please note that
162sending the patch _properly_ is not as trivial as you may think. Some mail
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +0000163clients convert TABs to spaces or word wrap long lines automatically, which
164will result in your patch being rejected as it will not apply with 'git apply'.
165
fd5c06c0
CC
Christophe CURIS2014-03-02 00:44:15 +0100166You could send the patch as an attachement to the mail, but this generally
167makes it a bit harder to review, and a lot harder to comment on; that's why
168the preferred method is inlined patches (like Git does).
169
8b049dec
CM
Carlos R. Mafra2012-01-14 15:11:21 +0000170Ideally your patch should contain a very good commit message that explains
171why you wrote the patch in the first place (see "Writing the commit log").
172In this case you can simply send the file(s) created in the 'git format-patch'
173step above as the sole content of your email to the mailing list. All your
174reasons and explanations will be in the commit log, and your email will look
175like:
176
177**********************************
178From: someone@someplace
179Subject: [PATCH] Fix something
180
181The commit message.
6c2a5f19 Christophe CURIS2011-07-17 12:20:13 +0200182
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +0000183The diff itself.
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +0200184
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +0000185**********************************
781b6633 Carlos R. Mafra2009-10-11 17:14:53 +0200186
8b049dec Carlos R. Mafra2012-01-14 15:11:21 +0000187Read the file email-clients.txt in the topdir of the wmaker-crm repository
0e99f6ea Christophe CURIS2014-03-02 00:44:17 +0100188to be advised on how to tweak your email client to avoid common pitfalls.
781b6633
CM
Carlos R. Mafra2009-10-11 17:14:53 +0200189
190___________________
191Example .gitconfig
192-------------------
193
194[user]
195 name = Erwin Schrodinger
196 email = schrodinger@gmail.com
197[core]
198 editor = xjed
199[status]
200 showUntrackedFiles = no
201[color]
202 branch = auto
203 status = auto
204 diff = auto
205 ui = auto
206[apply]
207 whitespace = fix
208
209
210
211
212