This is a short summary of guidelines you should try to follow when submitting patches to calcurse.

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 repository.

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

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

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 git rm 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 <ruskie@codemages.net>
Signed-off-by: Lukas Fleischer <lfleischer@calcurse.org>

The -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.

Creating a patch series

As soon as you finished all your work, test everything again and create a patch series:

$ git format-patch master

Replace master by maint if your development branch is based on the maintenance branch:

$ git format-patch maint

Submitting patches

Send your patch series to one of the mailing lists:

$ git send-email *.patch

The bugs mailing list should be used for bug fixes, misc should be used for everything else.

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 ---.

Importing patches

Git also provides a tool for importing a patch series submitted via git 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 A:

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.