This is a short summary of guidelines you should try to follow when submitting patches to calcurse.
1. Fetching the most recent source
The whole source code currently is under version control using Git as VCS. You can retrieve a local copy of the development tree using:
$ git clone git://git.calcurse.org/calcurse.git
This will create a new directory
calcurse that contains the cloned
If you want to follow the maintenance branch (
maint) as well (e.g. to create
a bug fix), setting up a tracking branch is recommended:
$ git branch -t maint origin/maint
2. Creating a working branch
Whenever you want to work on a new feature, do it in a separate branch. Having
diverging commits in the
master branch might cause conflicts when pulling in
new changes. Thus, creating a new development branch before doing any changes
is good practice. And even before doing that, you should update the master
branch of your working copy:
$ git checkout master $ git pull origin master $ git checkout -b wip
You can replace
wip by any name you like.
Maintenance patches such as bug fixes and stability improvements should be
based on the
maint branch instead:
$ git checkout maint $ git pull origin maint $ git checkout -b wip-maint
3. Committing the changes
Edit files in the source tree and test your changes. When everything seems to be fine, you’re ready to commit to your local working tree:
$ git commit -as
If you added or removed files, you probably need to run
git add or
before committing so that Git is aware of them.
If you work on more than a small bug fix, you should split your work into several commits. Try to keep your commits small and focused. Smaller patches are way easier to review and have a better chance of being included in mainline development.
Also try to make your commit messages brief and descriptive. The first line of
the commit message should be a short description (not more than 50 characters)
and should use imperative, present tense. If there are details that cannot be
expressed in these size constraints, put them in separate text paragraphs
separated by blank lines and wrapped to 72 columns. If you use Vim,
gitcommit.vim will do most of the job for you.
Here’s a sample commit message:
Invoke vars_init() before importing data with "-i" We forgot to call vars_init() when importing an item using the "-i" command line argument, which led to the pager configuration variable being unset and hence the pager invocation (triggered to show the log in case there are any errors during import) failing. Fix this by calling vars_init() before io_import_data(). Reported-by: Andraž 'ruskie' Levstik <email@example.com> Signed-off-by: Lukas Fleischer <firstname.lastname@example.org>
-s in the
git commit invocation makes Git add a "Signed-off-by" line to
credit yourself and to confirm that your contribution was created in whole or
in part by you and you have the right to submit it under the BSD license.
Please do not remove that line when editing the commit message.
4. Creating a patch series
As soon as you finished all your work, test everything again and create a patch series:
$ git format-patch master
maint if your development branch is based on the
$ git format-patch maint
5. Submitting patches
Send your patch series to one of the mailing lists:
$ git send-email *.patch
bugs mailing list should be used for bug fixes,
misc should be used for
You can also add a cover letter and/or add annotations to patches:
$ git send-email --cover-letter --annotate *.patch
Additional information on the particular patches, which shouldn’t appear in the
commit message itself, can be added immediately after the
6. Importing patches
Git also provides a tool for importing a patch series submitted via
send-email. Just save all mails that contain patches into mbox files and use
git am to apply them to your working branch:
$ git am <mbox>...
If you use mutt, you can also add following macro to apply the patch contained
in the current mail to your local Git repository by pressing
set mbox_type=mbox set my_git_repo_path=$HOME/src/calcurse macro index,pager A "<pipe-message>(cd $my_git_repo_path && git am)<enter>"
To setup different Git repositories per mailing list (in case you follow several
different development lists), simply bind the macro to a
folder-hook or to a
message-hook and use different repository paths per hook.