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 You will probably want also to run this in the end, because it does some
  36 checks on the source tree:
  37
  38 make check
  39
  40 __________________________
  41 Producing a patch with git
  42 --------------------------
  43
  44 You have the wmaker source and you want to write a patch in order to fix
  45 a bug or improve something. A possible work-flow is the following:
  46
  47 # Optional: Create a new branch (to be safe in case you screw up)
  48 git checkout -b fixbug
  49
  50 Now you fix the bug...
  51
  52 # Check what you did, review etc
  53 git diff
  54
  55 # if it looks good, commit your changes
  56 git commit -a
  57
  58 Git will open the editor set in your .gitconfig and you'll have to write a
  59 commit message. Writing a good message is as important as the source code
  60 modifications you've just made! See "Writing the commit log" for advice.
  61
  62 # Prepare the patch to submit to the mailing-list.
  63 # (use HEAD~2 if you want patches for the last 2 commits etc)
  64 git format-patch HEAD~1
  65
  66 # If you have created your own branch, and want all your commits created
  67 # after the #next branch, you can use:
  68 git format-patch next
  69
  70
  71 In order to ensure consistency in the code, there's an extra step to
  72 check the patchs. You should run this script (inherited from the Linux
  73 kernel) on the patch files generated and fix your commits for what it
  74 reports:
  75
  76 ./checkpatch.pl 00*
  77
  78 ______________________
  79 Writing the commit log
  80 ----------------------
  81
  82 You had a motivation to write your patch, you studied the sources and you
  83 found a way to do what you wanted to do. This whole process takes time and
  84 other people will not want to invest that time to rediscover what you've
  85 already found.
  86
  87 So the main reason for the commit message is to explain to other people what
  88 you did, _why_ and _how_. And you must assume that the person you must explain
  89 these things to will not be as familiar with the code you just modified as you
  90 are right after writing the patch -- and that includes yourself in a year or
  91 so. Be verbose in all the steps below.
  92
  93 The good commit log will start with the reason for writing the patch.
  94
  95 For example, if you use wmaker in some way and you expect that X happens but
  96 you get Y, you should say that very clearly. Sometimes that's enough for other
  97 more experienced people to know how to solve your issue. They will be able to
  98 judge your patch better if they know what you wanted to do -- sometimes there
  99 can be a better way to fix it.
 100
 101 Then you should explain why the wmaker source leads to Y and not to X.
 102
 103 Technical stuff can be expected at this point, e.g. "upon doing xyz in function
 104 foobar(), wmaker sets the variable foo to 'y' instead of setting it to 'x', and
 105 that will lead to blabla happening in function foobar_squared()...".
 106
 107 And finally you explain how you fixed it.
 108
 109 "You have to set foo to 'x', because then when the function foobar_squared() is
 110 called it will do X instead of Y because..."
 111
 112 At this point other people will have a clear understanding of what you did with
 113 minimal effort. And that leads to better patch reviews.
 114
 115 Furthermore, the above reasons should also tell you that you must not do
 116 more than one thing in the same patch. Again:
 117
 118        "Each patch must do one thing and one thing only."
 119
 120 If your patch does too much of unrelated stuff, it makes reviewing a nightmare
 121 and long-term maintenance much worse (think about a patch which introduces a
 122 regression in the middle of many other nice improvements, and now you have to
 123 get rid of the regression without removing the improvements -- 'git revert'
 124 will not help you here).
 125
 126 If you find yourself having troubles to write what you did in the commit
 127 message, perhaps you did too much. In this case you should split your patch
 128 into smaller unrelated pieces and produce a patch series. Unfortunately it's
 129 more work for you, but it's much better for wmaker.
 130
 131 _____________________________________
 132 Sending the patch to the mailing list
 133 -------------------------------------
 134
 135 Send your patches to:
 136
 137 wmaker-dev@googlegroups.com
 138
 139 Please do not send patches to any individual developer unless you have a very
 140 good reason to avoid more people being able to comment (and improve) on your
 141 patches.
 142
 143 The HIGHLY RECOMMENDED way to send a patch is to actually let Git do it for
 144 you, 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)
 148 git config --global sendemail.smtpserver "smtp.example.com"
 149 git config --global sendemail.validate   true
 150 git config sendemail.to "Window Maker Devel <wmaker-dev@googlegroups.com>"
 151
 152 # If you're sending more than 1 patch, you may be interested in having an
 153 # introduction mail for the batch:
 154 git format-patch  --cover-letter  next
 155 vi/emacs/nedit/whatever 0000-cover-letter.patch
 156
 157 # When you're satisfied, ask Git to mail all the patches:
 158 git send-email 00*
 159
 160
 161 If you do not want or cannot let Git send them for you, please note that
 162 sending the patch _properly_ is not as trivial as you may think. Some mail
 163 clients convert TABs to spaces or word wrap long lines automatically, which
 164 will result in your patch being rejected as it will not apply with 'git apply'.
 165
 166 You could send the patch as an attachement to the mail, but this generally
 167 makes it a bit harder to review, and a lot harder to comment on; that's why
 168 the preferred method is inlined patches (like Git does).
 169
 170 Ideally your patch should contain a very good commit message that explains
 171 why you wrote the patch in the first place (see "Writing the commit log").
 172 In this case you can simply send the file(s) created in the 'git format-patch'
 173 step above as the sole content of your email to the mailing list. All your
 174 reasons and explanations will be in the commit log, and your email will look
 175 like:
 176
 177 **********************************
 178 From: someone@someplace
 179 Subject: [PATCH] Fix something
 180
 181 The commit message.
 182
 183 The diff itself.
 184
 185 **********************************
 186
 187 Read the file email-clients.txt in the topdir of the wmaker-crm repository
 188 to be advised on how to tweak your email client to avoid common pitfalls.
 189
 190 ___________________
 191 Example .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