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