mirror of
https://github.com/gryf/wmaker.git
synced 2025-12-23 22:52:34 +01:00
8b049dec73
Try to convince other people why having non-trivial patches with empty commit messages are frowned upon.
154 lines
5.2 KiB
Plaintext
154 lines
5.2 KiB
Plaintext
____________
|
|
Introduction
|
|
------------
|
|
|
|
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'. See the end of this file
|
|
for an example .gitconfig.
|
|
|
|
To clone the wmaker-crm repository you can do:
|
|
|
|
git clone git://repo.or.cz/wmaker-crm.git
|
|
|
|
__________________________
|
|
Producing a patch with git
|
|
--------------------------
|
|
|
|
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.
|
|
|
|
# Optional: Create a new branch (to be safe in case you screw up)
|
|
git checkout -b fixbug
|
|
|
|
Now you fix the bug...
|
|
|
|
# Check what you did, review etc
|
|
git diff
|
|
|
|
# if it looks good, commit your changes
|
|
git commit -a
|
|
|
|
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.
|
|
# (use HEAD~2 if you want patches for the last 2 commits etc)
|
|
git format-patch HEAD~1
|
|
|
|
______________________
|
|
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:
|
|
|
|
wmaker-dev@lists.windowmaker.org
|
|
|
|
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.
|
|
|
|
The diff itself.
|
|
|
|
**********************************
|
|
|
|
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
|
|
-------------------
|
|
|
|
[user]
|
|
name = Erwin Schrodinger
|
|
email = schrodinger@gmail.com
|
|
[core]
|
|
editor = xjed
|
|
[status]
|
|
showUntrackedFiles = no
|
|
[color]
|
|
branch = auto
|
|
status = auto
|
|
diff = auto
|
|
ui = auto
|
|
[apply]
|
|
whitespace = fix
|
|
|
|
|
|
|
|
|
|
|