DevelopersProcess

Version 13 (Dan Smith, 07/14/2013 09:41 am)

1 1 Dan Smith
h1. CHIRP Development Process
2 6 Dan Smith
3 5 Dan Smith
{{>toc}}
4 6 Dan Smith
5 1 Dan Smith
h2. Mercurial Configuration
6 1 Dan Smith
7 10 Dan Smith
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/hgrc@. 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:
8 1 Dan Smith
9 1 Dan Smith
<pre>
10 1 Dan Smith
[ui]
11 1 Dan Smith
username = Joe Bob <joebob@gmail.com>
12 1 Dan Smith
[extensions]
13 1 Dan Smith
hgext.mq=
14 1 Dan Smith
hgext.patchbomb=
15 7 Dan Smith
16 1 Dan Smith
[email]
17 1 Dan Smith
from = Joe Bob <joebob@gmail.com>
18 1 Dan Smith
method = smtp
19 1 Dan Smith
20 1 Dan Smith
[smtp]
21 1 Dan Smith
host = smtp.gmail.com
22 1 Dan Smith
</pre>
23 1 Dan Smith
24 13 Dan Smith
h2. Getting the code
25 13 Dan Smith
26 13 Dan Smith
<pre>
27 13 Dan Smith
hg clone http://d-rats.com/hg/chirp.hg
28 13 Dan Smith
cd chirp.hg
29 13 Dan Smith
</pre>
30 13 Dan Smith
31 3 Dan Smith
h2. Bug Tracking
32 3 Dan Smith
33 3 Dan Smith
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.
34 3 Dan Smith
35 1 Dan Smith
h2. Submitting a patch
36 1 Dan Smith
37 2 Dan Smith
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.
38 2 Dan Smith
39 2 Dan Smith
h3. Making a change
40 2 Dan Smith
41 2 Dan Smith
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:
42 2 Dan Smith
43 2 Dan Smith
<pre>
44 2 Dan Smith
% hg status -mar
45 2 Dan Smith
M chirp/ic2820.py
46 2 Dan Smith
% hg diff
47 2 Dan Smith
diff -r a132c837fd25 chirp/ic2820.py
48 2 Dan Smith
--- a/chirp/ic2820.py   Mon Dec 24 08:17:19 2012 -0800
49 2 Dan Smith
+++ b/chirp/ic2820.py   Mon Dec 24 08:56:29 2012 -0800
50 2 Dan Smith
@@ -16,6 +16,8 @@
51 2 Dan Smith
 from chirp import chirp_common, icf, util, directory
52 2 Dan Smith
 from chirp import bitwise
53 2 Dan Smith
 
54 2 Dan Smith
+# Just added a comment
55 2 Dan Smith
+
56 2 Dan Smith
 MEM_FORMAT = """
57 2 Dan Smith
 struct {
58 2 Dan Smith
   u32  freq;
59 2 Dan Smith
</pre>
60 2 Dan Smith
61 2 Dan Smith
The first command shows me that @chirp/ic2820.py@ has been modified, and the second shows me the actual changes that have been made.
62 2 Dan Smith
63 2 Dan Smith
h3. Soft-committing a Change
64 2 Dan Smith
65 11 Tom Hayward
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 mitigate 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:
66 2 Dan Smith
67 2 Dan Smith
<pre>
68 11 Tom Hayward
% hg qnew -ef mypatch     # Here an editor will open to compose a commit message
69 2 Dan Smith
% hg qapplied             # This shows that the patch is now applied
70 11 Tom Hayward
mypatch
71 2 Dan Smith
</pre>
72 2 Dan Smith
73 11 Tom Hayward
This example takes the changes I made above, and commits them into a new patch called @mypatch@. I can now look at the patch in its entirety, as well as add or remove it from my local tree:
74 2 Dan Smith
75 11 Tom Hayward
| Command | Description |
76 11 Tom Hayward
| @hg export tip@           | This will show me the whole patch, with the commit message |
77 11 Tom Hayward
| @hg export tip > mypatch.patch@ | This will save the patch, including commit message, to mypatch.patch. You can then attach this file to an email for submission. |
78 11 Tom Hayward
| @hg qpop@                 | Remove it from the tree |
79 11 Tom Hayward
| @hg qapplied@             | This shows that no patches are applied |
80 11 Tom Hayward
| @hg qunapplied
81 11 Tom Hayward
mypatch@                   | This shows that our patch is not applied |
82 11 Tom Hayward
| @hg qpush@                | This adds the patch back to the tree |
83 11 Tom Hayward
| @hg qapplied
84 11 Tom Hayward
mypatch@                   | This shows that our patch is applied |
85 11 Tom Hayward
| @hg qpop@                 | This removes it again |
86 11 Tom Hayward
| @hg qdel mypatch@         | This deletes it permanently |
87 2 Dan Smith
88 12 Tom Hayward
If this tool intrigues you, you can learn how to use it here: http://mercurial.selenic.com/wiki/MqTutorial
89 12 Tom Hayward
90 4 Dan Smith
h3. Testing
91 4 Dan Smith
92 4 Dan Smith
CHIRP has a modest test suite used to validate driver behavior in the @tests/@ directory. Before submitting a patch, please ensure that all the tests run and pass (or at least pass as well as before you made the change). To run the whole set, do this:
93 4 Dan Smith
94 4 Dan Smith
<pre>
95 4 Dan Smith
% cd tests
96 4 Dan Smith
% ./run_tests
97 4 Dan Smith
</pre>
98 4 Dan Smith
99 8 Dan Smith
Note that on Windows, you probably want to run the script like this:
100 8 Dan Smith
101 8 Dan Smith
<pre>
102 9 Dan Smith
C:\Users\Foo\chirp.hg\tests> python run_tests
103 8 Dan Smith
</pre>
104 8 Dan Smith
105 4 Dan Smith
To run just a single driver's tests:
106 4 Dan Smith
107 4 Dan Smith
<pre>
108 4 Dan Smith
% ./run_tests -d Icom_IC-2820H
109 4 Dan Smith
</pre>
110 4 Dan Smith
111 4 Dan Smith
To run just a specific test:
112 4 Dan Smith
113 4 Dan Smith
<pre>
114 4 Dan Smith
% ./run_tests -t Edges
115 4 Dan Smith
</pre>
116 4 Dan Smith
117 4 Dan Smith
If you are adding a new driver, you will need to add an image to the @tests/images/@ directory which is correctly named for your model. These do not communicate well in patch form, so just send a sample image to the development mailing list to accompany your patch submission.
118 4 Dan Smith
119 4 Dan Smith
Note: Please make sure that all the tests run, not just the one that affects your driver. Several of the drivers play off each other and sometimes changes to one will break another.
120 4 Dan Smith
121 2 Dan Smith
h3. Sending a change
122 2 Dan Smith
123 2 Dan Smith
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:
124 2 Dan Smith
125 2 Dan Smith
<pre>
126 2 Dan Smith
% hg export tip > add_comment.patch
127 2 Dan Smith
</pre>
128 2 Dan Smith
129 2 Dan Smith
You can also configure the tool to email it directly, in which case you need only do:
130 2 Dan Smith
131 2 Dan Smith
<pre>
132 2 Dan Smith
% hg email tip
133 2 Dan Smith
</pre>
134 2 Dan Smith
135 2 Dan Smith
You will be prompted for the destination address.
136 3 Dan Smith
137 3 Dan Smith
h2. Patch Guidelines
138 3 Dan Smith
139 3 Dan Smith
h3. The Commit Message
140 3 Dan Smith
141 3 Dan Smith
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:
142 3 Dan Smith
143 3 Dan Smith
<pre>
144 3 Dan Smith
[uv5r] Add support for firmware >= 291
145 3 Dan Smith
</pre>
146 3 Dan Smith
147 3 Dan Smith
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.
148 3 Dan Smith
149 3 Dan Smith
h3. Scope
150 3 Dan Smith
151 3 Dan Smith
Guidelines:
152 3 Dan Smith
153 3 Dan Smith
 * Patches should be small and concise. Try to keep a single standing change to a single patch.
154 3 Dan Smith
 * Don't fix several bugs in a single patch, unless there is a technical reason to do so.
155 3 Dan Smith
 * Don't fix, cleanup, or change random whitespace in the patch unless that is the sole purpose of the patch.