193 lines
6.2 KiB
Plaintext
193 lines
6.2 KiB
Plaintext
////
|
|
/*
|
|
* Copyright (c) 2004-2023 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 <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.
|