diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 5 | ||||
| -rw-r--r-- | doc/calcurse.1.txt | 3 | ||||
| -rw-r--r-- | doc/manual.txt | 13 | ||||
| -rw-r--r-- | doc/submitting-patches.txt | 192 |
4 files changed, 210 insertions, 3 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index caa90d2..5888b18 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,17 +14,20 @@ A2X_ARGS = \ endif dist_doc_DATA = \ - manual.html + manual.html \ + submitting-patches.html dist_man_MANS = \ calcurse.1 EXTRA_DIST = \ manual.txt \ + submitting-patches.txt \ calcurse.1.txt CLEANFILES = \ manual.html \ + submitting-patches.html \ calcurse.1 docdir = $(datadir)/doc/$(PACKAGE) diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt index 884aa34..f611079 100644 --- a/doc/calcurse.1.txt +++ b/doc/calcurse.1.txt @@ -103,6 +103,9 @@ appointments can be specified using the *-c* flag. Specify the data directory to use. This option is incompatible with -c. If not specified, the default directory is *~/.calcurse/*. +*-g*, *--gc*:: + Run the garbage collector for note files and exit. + *-h*, *--help*:: Print a short help text describing the supported command-line options, and exit. diff --git a/doc/manual.txt b/doc/manual.txt index c0a992d..4964a21 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -113,8 +113,7 @@ library already installed on your computer, but if not, you can find it at the following url: http://ftp.gnu.org/pub/gnu/ncurses/ NOTE: It is also possible to link `calcurse` against the `ncursesw` library - (ncurses with support for unicode). However, UTF-8 is not yet supported - by `calcurse`. + (ncurses with support for unicode). [[install_requirements_gettext]] gettext library @@ -210,6 +209,9 @@ can be specified using the `-c` flag. Specify the data directory to use. This option is incompatible with -c. If not specified, the default directory is `~/.calcurse/`. +`-g, --gc`:: + Run the garbage collector for note files and exit. + `-h, --help`:: Print a short help text describing the supported command-line options, and exit. @@ -624,6 +626,9 @@ These options control `calcurse` general behavior, as described below: will be automatically saved if `auto_save` is set to *no*. This means the user must press `S` (for saving) in order to retrieve its modifications. +`auto_gc` (default: *no*):: + Automatically run the garbage collector for note files when quitting. + `periodic_save` (default: *0*):: If different from `0`, user's data will be automatically saved every *periodic_save* minutes. When an automatic save is performed, two asterisks @@ -805,6 +810,10 @@ $ calcurse --next | mail -s "[calcurse] upcoming appointment!" user@host.com ---- ==== +`notify-all` (default: *no*):: + Invert the sense of flagging an appointment as `important`. If this is + enabled, all appointments will be notified - except for flagged ones. + `notify-daemon_enable` (default: *no*):: If set to yes, daemon mode will be enabled, meaning `calcurse` will run into background when the user's interface is exited. This will allow the 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. |