CHIRP

h1. CHIRP Development Process

h2. Mercurial Configuration

Make sure that your mercurial tool is configured properly for CHIRP. This means having the correct username and email address specified, as well as the MQ extension enabled (for most cases). You can do this in your global mercurial configuration file, or in the one in the repository you're working on, which is @.hg/config@. You may also want to ensure that it has the patchbomb configuration enabled, which allows easy emailing out of mercurial itself. You probably want the following lines in your config file:

<pre>

[ui]

username = Joe Bob <joebob@gmail.com>

[extensions]

hgext.mq=

hgext.patchbomb=

[email]

from = Joe Bob <joebob@gmail.com>

method = smtp

[smtp]

host = smtp.gmail.com

</pre>

h2. Bug Tracking

All changes should have a bug created on the tracker before submission. The server hosting the repository will not allow changesets to be pushed that do not contain a bug number (see below). It is perfectly reasonable to create a bug, assign it to yourself, and then close it before sending the patch.

h2. Submitting a patch

Changes to CHIRP are welcome, but they should be in the correct format, and sent as a patch to the mailing list. The correct way to do this is to clone the upstream repository, make your changes there, and then soft-commit them as MQ patches to the tree. The following assumes you have cloned the repository and are in the resulting directory.

h3. Making a change

Edit one of the files to make a change. For this example, I'll use @chirp/ic2820.py@. Assuming I have made a change, the following commands help me see what has been done:

<pre>

% hg status -mar

M chirp/ic2820.py

% hg diff

diff -r a132c837fd25 chirp/ic2820.py

--- a/chirp/ic2820.py   Mon Dec 24 08:17:19 2012 -0800

+++ b/chirp/ic2820.py   Mon Dec 24 08:56:29 2012 -0800

@@ -16,6 +16,8 @@

 from chirp import chirp_common, icf, util, directory

 from chirp import bitwise

+# Just added a comment

+

 MEM_FORMAT = """

 struct {

   u32  freq;

</pre>

The first command shows me that @chirp/ic2820.py@ has been modified, and the second shows me the actual changes that have been made.

h3. Soft-committing a Change

You can commit a change directly to your tree, but it becomes a little more complicated to make changes to it if necessary, and it creates a fork when the change is actually accepted upstream. An easy way to manage all of this is to soft-commit your changes as MQ patches. Assuming you have made the change above, the following example shows the process for committing that into a patch:

<pre>

% hg qnew -ef add_comment # Here I will be prompted to enter a commit message

% hg qapplied             # This shows that the patch is now applied

add_comment

</pre>

This example takes the changes I made above, and commits them into a new patch called @add_comment@. I can now look at the patch in its entirety, as well as add or remove it from my local tree:

<pre>

% hg export tip           # This will show me the whole patch, with the commit message

% hg qpop                 # Remove it from the tree

% hg qapplied             # This shows that no patches are applied

% hg qunapplied           # This shows that our patch is not applied

add_comment

% hg qpush                # This adds the patch back to the tree

% hg qapplied             # This shows that our patch is applied

add_comment

% hg qpop                 # This removes it again

% hg qdel add_comment     # This deletes it permanently

</pre>

h3. Sending a change

There are two ways to do this. First, you can export the patch to a text file and email it to the list with your normal mailer. This is how:

<pre>

% hg export tip > add_comment.patch

</pre>

You can also configure the tool to email it directly, in which case you need only do:

<pre>

% hg email tip

</pre>

You will be prompted for the destination address.

h2. Patch Guidelines

h3. The Commit Message

The commit message should have a first line that stands on its own and describes the patch briefly. If it pertains to a specific driver, put that driver's short name in brackets at the beginning. For example:

<pre>

[uv5r] Add support for firmware >= 291

</pre>

After the first line, more descriptive text may be added (and is appreciated) about what and why the change is being made. At the end, you must include a bug number in the format @#XXX@. This lets the system correlate changes to bugs, which helps during release time.

h3. Scope

Guidelines:

 * Patches should be small and concise. Try to keep a single standing change to a single patch.

 * Don't fix several bugs in a single patch, unless there is a technical reason to do so.

 * Don't fix, cleanup, or change random whitespace in the patch unless that is the sole purpose of the patch.