diff options
Diffstat (limited to 'doc/submitting-patches.txt')
| -rw-r--r-- | doc/submitting-patches.txt | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt new file mode 100644 index 0000000..6fbb5cd --- /dev/null +++ b/doc/submitting-patches.txt @@ -0,0 +1,192 @@ +//// +/* + * Copyright (c) 2004-2011 calcurse Development Team <misc@calcurse.org> + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above + * copyright notice, this list of conditions and the + * following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the + * following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +//// + +CALCURSE - Submitting Patches +============================= + +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 <calcurse@cryptocrack.de> +---- + +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. |