WPrefs: Moved widgets in Workspace panel so that label is not truncated
[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 __________________________
17 Producing a patch with git
18 --------------------------
19
20 You have the wmaker source and you want to write a patch in order to fix
21 a bug or improve something. A possible workflow is the following.
22
23 # Optional: Create a new branch (to be safe in case you screw up)
24 git checkout -b fixbug
25
26 Now you fix the bug...
27
28 # Check what you did, review etc
29 git diff
30
31 # if it looks good, commit your changes
32 git commit -a
33
34 Git will open the editor set in your .gitconfig and you'll have to write a
35 commit message. Writing a good message is as important as the source code
36 modifications you've just made! See "Writing the commit log" for advice.
37
38 # Prepare the patch to submit to the mailing-list.
39 # (use HEAD~2 if you want patches for the last 2 commits etc)
40 git format-patch HEAD~1
41
42 ______________________
43 Writing the commit log
44 ----------------------
45
46 You had a motivation to write your patch, you studied the sources and you
47 found a way to do what you wanted to do. This whole process takes time and
48 other people will not want to invest that time to rediscover what you've
49 already found.
50
51 So the main reason for the commit message is to explain to other people what
52 you did, _why_ and _how_. And you must assume that the person you must explain
53 these things to will not be as familiar with the code you just modified as you
54 are right after writing the patch -- and that includes yourself in a year or
55 so. Be verbose in all the steps below.
56
57 The good commit log will start with the reason for writing the patch.
58
59 For example, if you use wmaker in some way and you expect that X happens but
60 you get Y, you should say that very clearly. Sometimes that's enough for other
61 more experienced people to know how to solve your issue. They will be able to
62 judge your patch better if they know what you wanted to do -- sometimes there
63 can be a better way to fix it.
64
65 Then you should explain why the wmaker source leads to Y and not to X.
66
67 Technicall stuff can be expected at this point, e.g. "upon doing xyz in function
68 foobar(), wmaker sets the variable foo to 'y' instead of setting it to 'x', and
69 that will lead to blabla happening in function foobar_squared()...".
70
71 And finally you explain how you fixed it.
72
73 "You have to set foo to 'x', because then when the function foobar_squared() is
74 called it will do X instead of Y because..."
75
76 At this point other people will have a clear understanding of what you did with
77 minimal effort. And that leads to better patch reviews.
78
79 Furthermore, the above reasons should also tell you that you must not do
80 more than one thing in the same patch. Again:
81
82        "Each patch must do one thing and one thing only."
83
84 If your patch does too much of unrelated stuff, it makes reviewing a nightmare
85 and long-term mantainance much worse (think about a patch which introduces a
86 regression in the middle of many other nice improvements, and now you have to
87 get rid of the regression without removing the improvements -- 'git revert'
88 will not help you here).
89
90 If you find yourself having troubles to write what you did in the commit
91 message, perhaps you did too much. In this case you should split your patch
92 into smaller unrelated pieces and produce a patch series. Unfortunately it's
93 more work for you, but it's much better for wmaker.
94
95 _____________________________________
96 Sending the patch to the mailing list
97 -------------------------------------
98
99 Send your patches to:
100
101 wmaker-dev@lists.windowmaker.org
102
103 Please do not send patches to any individual developer unless you have a very
104 good reason to avoid more people being able to comment (and improve) on your
105 patches.
106
107 Sending the patch _properly_ is not as trivial as you might think. Some mail
108 clients convert TABs to spaces or word wrap long lines automatically, which
109 will result in your patch being rejected as it will not apply with 'git apply'.
110
111 Ideally your patch should contain a very good commit message that explains
112 why you wrote the patch in the first place (see "Writing the commit log").
113 In this case you can simply send the file(s) created in the 'git format-patch'
114 step above as the sole content of your email to the mailing list. All your
115 reasons and explanations will be in the commit log, and your email will look
116 like:
117
118 **********************************
119 From: someone@someplace
120 Subject: [PATCH] Fix something
121
122 The commit message.
123
124 The diff itself.
125
126 **********************************
127
128 Read the file email-clients.txt in the topdir of the wmaker-crm repository
129 to be adviced on how to tweak your email client to avoid common pitfalls.
130
131 ___________________
132 Example .gitconfig
133 -------------------
134
135 [user]
136         name = Erwin Schrodinger
137         email = schrodinger@gmail.com
138 [core]
139         editor = xjed
140 [status]
141         showUntrackedFiles = no
142 [color]
143         branch = auto
144         status = auto
145         diff = auto
146         ui = auto
147 [apply]
148         whitespace = fix
149         
150
151
152
153