Project

General

Profile

DevelopersProcess » History » Version 17

Brian Dickman, 09/05/2016 10:43 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
7 15 Robert Terzi
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@ in the top level chirp.hg directory. 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 16 Tom Hayward
to = chirp_devel@intrepid.danplanet.com
20 1 Dan Smith
21
[smtp]
22
host = smtp.gmail.com
23 16 Tom Hayward
port = 587
24
tls = True
25 1 Dan Smith
</pre>
26
27 13 Dan Smith
h2. Getting the code
28
29
<pre>
30
hg clone http://d-rats.com/hg/chirp.hg
31
cd chirp.hg
32
</pre>
33
34 3 Dan Smith
h2. Bug Tracking
35
36
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.
37
38 1 Dan Smith
h2. Submitting a patch
39
40 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.
41
42 14 Robert Terzi
You must include an Issue Number (#123) in the first line of the commit message to tie each patch to an issue for tracking purposes.
43
44 2 Dan Smith
h3. Making a change
45
46
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:
47
48
<pre>
49
% hg status -mar
50
M chirp/ic2820.py
51
% hg diff
52
diff -r a132c837fd25 chirp/ic2820.py
53
--- a/chirp/ic2820.py   Mon Dec 24 08:17:19 2012 -0800
54
+++ b/chirp/ic2820.py   Mon Dec 24 08:56:29 2012 -0800
55
@@ -16,6 +16,8 @@
56
 from chirp import chirp_common, icf, util, directory
57
 from chirp import bitwise
58
 
59
+# Just added a comment
60
+
61
 MEM_FORMAT = """
62
 struct {
63
   u32  freq;
64
</pre>
65
66
The first command shows me that @chirp/ic2820.py@ has been modified, and the second shows me the actual changes that have been made.
67
68
h3. Soft-committing a Change
69
70 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:
71 2 Dan Smith
72
<pre>
73 11 Tom Hayward
% hg qnew -ef mypatch     # Here an editor will open to compose a commit message
74 2 Dan Smith
% hg qapplied             # This shows that the patch is now applied
75 11 Tom Hayward
mypatch
76 2 Dan Smith
</pre>
77
78 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:
79 2 Dan Smith
80 11 Tom Hayward
| Command | Description |
81
| @hg export tip@           | This will show me the whole patch, with the commit message |
82 14 Robert Terzi
| @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 to chirp_devel for submission. |
83 15 Robert Terzi
| @hg email tip@   | If hg is correctly configured with your email address, name and SMTP server, it will automatically generate an email with the patch included. It will prompt you for the To: address. |
84 14 Robert Terzi
85 15 Robert Terzi
86 14 Robert Terzi
See "Sending a Change" below.
87
88
89
h3. Working with Patches (mq mercurial extension)
90
91
The following commands demonstrate how the mq extension to hg can be used for managing patches.
92
93
| Command | Description |
94
| @hg export tip@           | This will show me the whole patch, with the commit message |
95 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. |
96
| @hg qpop@                 | Remove it from the tree |
97
| @hg qapplied@             | This shows that no patches are applied |
98
| @hg qunapplied
99
mypatch@                   | This shows that our patch is not applied |
100
| @hg qpush@                | This adds the patch back to the tree |
101
| @hg qapplied
102
mypatch@                   | This shows that our patch is applied |
103
| @hg qpop@                 | This removes it again |
104
| @hg qdel mypatch@         | This deletes it permanently |
105 2 Dan Smith
106 12 Tom Hayward
If this tool intrigues you, you can learn how to use it here: http://mercurial.selenic.com/wiki/MqTutorial
107
108 4 Dan Smith
h3. Testing
109
110
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:
111
112
<pre>
113
% cd tests
114
% ./run_tests
115
</pre>
116
117 8 Dan Smith
Note that on Windows, you probably want to run the script like this:
118
119
<pre>
120 9 Dan Smith
C:\Users\Foo\chirp.hg\tests> python run_tests
121 8 Dan Smith
</pre>
122
123 4 Dan Smith
To run just a single driver's tests:
124
125
<pre>
126
% ./run_tests -d Icom_IC-2820H
127
</pre>
128
129
To run just a specific test:
130
131
<pre>
132
% ./run_tests -t Edges
133
</pre>
134
135
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.
136
137
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.
138 1 Dan Smith
139 15 Robert Terzi
h3. Sending a change
140 2 Dan Smith
141
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:
142
143
<pre>
144
% hg export tip > add_comment.patch
145
</pre>
146
147
You can also configure the tool to email it directly, in which case you need only do:
148
149
<pre>
150
% hg email tip
151
</pre>
152 3 Dan Smith
153
You will be prompted for the destination address.
154
155 17 Brian Dickman
h2. Setting up gmail for patchbomb email
156
157
If you have a gmail account, setup the port and TLS enable as shown above, then follow these extra steps to finish enabling:
158
159
# If you haven't enabled TFA (Two Factor Authentication) for your account, visit this link and follow the wizard:
160
161
https://myaccount.google.com/security/signinoptions/two-step-verification/enroll-welcome
162
163
# With TFA enabled, you can add app-specific passwords, like one for mercurial:
164
165
https://security.google.com/settings/security/apppasswords
166
167
With these steps complete, add the app-specific password to your hgrc, and you should be all set.
168
169 3 Dan Smith
h2. Patch Guidelines
170
171 1 Dan Smith
h3. The Commit Message
172 3 Dan Smith
173 14 Robert Terzi
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. An issue number from the issue tracking system must be included to tie the submitted patch to an open issue. For example:
174 3 Dan Smith
175
<pre>
176 14 Robert Terzi
[uv5r] Add support for firmware >= 291 Fixes #123
177 3 Dan Smith
</pre>
178
179
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.
180
181
h3. Scope
182
183
Guidelines:
184
185
 * Patches should be small and concise. Try to keep a single standing change to a single patch.
186
 * Don't fix several bugs in a single patch, unless there is a technical reason to do so.
187
 * Don't fix, cleanup, or change random whitespace in the patch unless that is the sole purpose of the patch.