Project

General

Profile

DevelopersProcess » History » Version 10

Dan Smith, 02/19/2013 06:13 PM

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
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
<pre>
10
[ui]
11
username = Joe Bob <joebob@gmail.com>
12
[extensions]
13
hgext.mq=
14
hgext.patchbomb=
15 7 Dan Smith
16 1 Dan Smith
[email]
17
from = Joe Bob <joebob@gmail.com>
18
method = smtp
19
20
[smtp]
21
host = smtp.gmail.com
22
</pre>
23
24 3 Dan Smith
h2. Bug Tracking
25
26
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.
27
28 1 Dan Smith
h2. Submitting a patch
29
30 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.
31
32
h3. Making a change
33
34
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:
35
36
<pre>
37
% hg status -mar
38
M chirp/ic2820.py
39
% hg diff
40
diff -r a132c837fd25 chirp/ic2820.py
41
--- a/chirp/ic2820.py   Mon Dec 24 08:17:19 2012 -0800
42
+++ b/chirp/ic2820.py   Mon Dec 24 08:56:29 2012 -0800
43
@@ -16,6 +16,8 @@
44
 from chirp import chirp_common, icf, util, directory
45
 from chirp import bitwise
46
 
47
+# Just added a comment
48
+
49
 MEM_FORMAT = """
50
 struct {
51
   u32  freq;
52
</pre>
53
54
The first command shows me that @chirp/ic2820.py@ has been modified, and the second shows me the actual changes that have been made.
55
56
h3. Soft-committing a Change
57
58
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:
59
60
<pre>
61
% hg qnew -ef add_comment # Here I will be prompted to enter a commit message
62
% hg qapplied             # This shows that the patch is now applied
63
add_comment
64
</pre>
65
66
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:
67
68
<pre>
69
% hg export tip           # This will show me the whole patch, with the commit message
70
% hg qpop                 # Remove it from the tree
71
% hg qapplied             # This shows that no patches are applied
72
% hg qunapplied           # This shows that our patch is not applied
73
add_comment
74
% hg qpush                # This adds the patch back to the tree
75
% hg qapplied             # This shows that our patch is applied
76
add_comment
77
% hg qpop                 # This removes it again
78
% hg qdel add_comment     # This deletes it permanently
79
</pre>
80
81 4 Dan Smith
h3. Testing
82
83
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:
84
85
<pre>
86
% cd tests
87
% ./run_tests
88
</pre>
89
90 8 Dan Smith
Note that on Windows, you probably want to run the script like this:
91
92
<pre>
93 9 Dan Smith
C:\Users\Foo\chirp.hg\tests> python run_tests
94 8 Dan Smith
</pre>
95
96 4 Dan Smith
To run just a single driver's tests:
97
98
<pre>
99
% ./run_tests -d Icom_IC-2820H
100
</pre>
101
102
To run just a specific test:
103
104
<pre>
105
% ./run_tests -t Edges
106
</pre>
107
108
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.
109
110
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.
111
112 2 Dan Smith
h3. Sending a change
113
114
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:
115
116
<pre>
117
% hg export tip > add_comment.patch
118
</pre>
119
120
You can also configure the tool to email it directly, in which case you need only do:
121
122
<pre>
123
% hg email tip
124
</pre>
125
126
You will be prompted for the destination address.
127 3 Dan Smith
128
h2. Patch Guidelines
129
130
h3. The Commit Message
131
132
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:
133
134
<pre>
135
[uv5r] Add support for firmware >= 291
136
</pre>
137
138
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.
139
140
h3. Scope
141
142
Guidelines:
143
144
 * Patches should be small and concise. Try to keep a single standing change to a single patch.
145
 * Don't fix several bugs in a single patch, unless there is a technical reason to do so.
146
 * Don't fix, cleanup, or change random whitespace in the patch unless that is the sole purpose of the patch.