DevelopersProcess

Version 33 (Dan Smith, 02/16/2019 08:18 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 33 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@ 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 can use your own outbound mail server for this, but if you do not have access to one, or do not want to configure authentication, it is easiest to just submit patch emails directly to the server that runs the mailing list. You probably want the following lines in your config file:
8 1 Dan Smith
9 23 Aaron P
h3. @chirp.hg/.hg/hgrc@
10 23 Aaron P
11 1 Dan Smith
<pre>
12 1 Dan Smith
[ui]
13 1 Dan Smith
username = Joe Bob <joebob@gmail.com>
14 1 Dan Smith
[extensions]
15 1 Dan Smith
hgext.mq=
16 1 Dan Smith
hgext.patchbomb=
17 7 Dan Smith
18 1 Dan Smith
[email]
19 1 Dan Smith
from = Joe Bob <joebob@gmail.com>
20 1 Dan Smith
method = smtp
21 16 Tom Hayward
to = chirp_devel@intrepid.danplanet.com
22 23 Aaron P
# Add a bcc if you want a copy of the email
23 23 Aaron P
# bcc = Joe Bob <joebob@gmail.com>
24 1 Dan Smith
25 1 Dan Smith
[smtp]
26 33 Dan Smith
host = intrepid.danplanet.com
27 16 Tom Hayward
port = 587
28 16 Tom Hayward
tls = True
29 31 Dan Smith
30 31 Dan Smith
[diff]
31 31 Dan Smith
git = True
32 1 Dan Smith
</pre>
33 1 Dan Smith
34 13 Dan Smith
h2. Getting the code
35 13 Dan Smith
36 13 Dan Smith
<pre>
37 13 Dan Smith
hg clone http://d-rats.com/hg/chirp.hg
38 13 Dan Smith
cd chirp.hg
39 13 Dan Smith
</pre>
40 13 Dan Smith
41 3 Dan Smith
h2. Bug Tracking
42 3 Dan Smith
43 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.
44 3 Dan Smith
45 1 Dan Smith
h2. Submitting a patch
46 1 Dan Smith
47 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.
48 2 Dan Smith
49 25 Dan Smith
You must include an Issue Number (#123) somewhere in the commit message to tie each patch to an issue for tracking purposes.
50 14 Robert Terzi
51 2 Dan Smith
h3. Making a change
52 2 Dan Smith
53 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:
54 2 Dan Smith
55 2 Dan Smith
<pre>
56 2 Dan Smith
% hg status -mar
57 2 Dan Smith
M chirp/ic2820.py
58 2 Dan Smith
% hg diff
59 2 Dan Smith
diff -r a132c837fd25 chirp/ic2820.py
60 2 Dan Smith
--- a/chirp/ic2820.py   Mon Dec 24 08:17:19 2012 -0800
61 2 Dan Smith
+++ b/chirp/ic2820.py   Mon Dec 24 08:56:29 2012 -0800
62 2 Dan Smith
@@ -16,6 +16,8 @@
63 2 Dan Smith
 from chirp import chirp_common, icf, util, directory
64 2 Dan Smith
 from chirp import bitwise
65 2 Dan Smith
 
66 2 Dan Smith
+# Just added a comment
67 2 Dan Smith
+
68 2 Dan Smith
 MEM_FORMAT = """
69 2 Dan Smith
 struct {
70 2 Dan Smith
   u32  freq;
71 2 Dan Smith
</pre>
72 2 Dan Smith
73 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.
74 2 Dan Smith
75 2 Dan Smith
h3. Soft-committing a Change
76 2 Dan Smith
77 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:
78 2 Dan Smith
79 2 Dan Smith
<pre>
80 11 Tom Hayward
% hg qnew -ef mypatch     # Here an editor will open to compose a commit message
81 2 Dan Smith
% hg qapplied             # This shows that the patch is now applied
82 11 Tom Hayward
mypatch
83 2 Dan Smith
</pre>
84 2 Dan Smith
85 32 Dan Smith
If you are adding a new file (i.e. your new driver) then don't forget to add it to the repository before creating or refreshing the patch:
86 32 Dan Smith
87 32 Dan Smith
<pre>
88 32 Dan Smith
% hg add chirp/drivers/mynewdriver.py
89 32 Dan Smith
% hg qnew -ef mypatch
90 32 Dan Smith
</pre>
91 32 Dan Smith
92 2 Dan Smith
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:
93 11 Tom Hayward
94 11 Tom Hayward
| Command | Description |
95 14 Robert Terzi
| @hg export tip@           | This will show me the whole patch, with the commit message |
96 15 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. |
97 14 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. |
98 15 Robert Terzi
99 14 Robert Terzi
See "Sending a Change" below.
100 14 Robert Terzi
101 14 Robert Terzi
102 14 Robert Terzi
h3. Working with Patches (mq mercurial extension)
103 14 Robert Terzi
104 14 Robert Terzi
The following commands demonstrate how the mq extension to hg can be used for managing patches.
105 14 Robert Terzi
106 14 Robert Terzi
| Command | Description |
107 14 Robert Terzi
| @hg export tip@           | This will show me the whole patch, with the commit message |
108 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. |
109 11 Tom Hayward
| @hg qpop@                 | Remove it from the tree |
110 11 Tom Hayward
| @hg qapplied@             | This shows that no patches are applied |
111 11 Tom Hayward
| @hg qunapplied
112 11 Tom Hayward
mypatch@                   | This shows that our patch is not applied |
113 11 Tom Hayward
| @hg qpush@                | This adds the patch back to the tree |
114 11 Tom Hayward
| @hg qapplied
115 11 Tom Hayward
mypatch@                   | This shows that our patch is applied |
116 11 Tom Hayward
| @hg qpop@                 | This removes it again |
117 11 Tom Hayward
| @hg qdel mypatch@         | This deletes it permanently |
118 20 Aaron P
| @hg strip --keep --rev .@  | Made an actual commit instead of using mq? This will unstage the last commit, similar to git reset --soft HEAD~1 |
119 2 Dan Smith
120 19 Aaron P
If this tool intrigues you, you can learn how to use it here: https://www.mercurial-scm.org/wiki/MqTutorial
121 12 Tom Hayward
122 4 Dan Smith
h3. Testing
123 4 Dan Smith
124 26 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).
125 1 Dan Smith
126 26 Dan Smith
In order to run the tests you will need tox installed:
127 26 Dan Smith
128 1 Dan Smith
<pre>
129 26 Dan Smith
% sudo pip install tox
130 1 Dan Smith
</pre>
131 8 Dan Smith
132 26 Dan Smith
To run the whole set, do this:
133 8 Dan Smith
134 9 Dan Smith
<pre>
135 26 Dan Smith
% tox
136 8 Dan Smith
</pre>
137 4 Dan Smith
138 4 Dan Smith
To run just a single driver's tests:
139 4 Dan Smith
140 1 Dan Smith
<pre>
141 26 Dan Smith
% tox -e driver -- -d Icom_IC-2820H
142 4 Dan Smith
</pre>
143 4 Dan Smith
144 4 Dan Smith
To run just a specific test:
145 4 Dan Smith
146 4 Dan Smith
<pre>
147 26 Dan Smith
% tox -e driver -- -t Edges
148 4 Dan Smith
</pre>
149 18 Brian Dickman
150 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 attach your test image to the issue on the tracker and send a heads-up to the devel list so it can be snagged into the repo.
151 4 Dan Smith
152 1 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.
153 15 Robert Terzi
154 2 Dan Smith
h3. Sending a change
155 2 Dan Smith
156 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:
157 2 Dan Smith
158 2 Dan Smith
<pre>
159 2 Dan Smith
% hg export tip > add_comment.patch
160 2 Dan Smith
</pre>
161 2 Dan Smith
162 2 Dan Smith
You can also configure the tool to email it directly, in which case you need only do:
163 2 Dan Smith
164 2 Dan Smith
<pre>
165 2 Dan Smith
% hg email tip
166 3 Dan Smith
</pre>
167 3 Dan Smith
168 3 Dan Smith
You will be prompted for the destination address.
169 22 Dan Smith
170 17 Brian Dickman
h2. Setting up *GMail* for patchbomb email
171 23 Aaron P
172 23 Aaron P
h3. Without two factor identification
173 21 Dan Smith
174 23 Aaron P
If you have a gmail account, setup the port and TLS enable as shown above. You can use your regular gmail username and password if you have not enabled two-factor authentication.
175 23 Aaron P
176 17 Brian Dickman
h3. With two factor identification
177 22 Dan Smith
178 17 Brian Dickman
If it bugs you to have your gmail password in a text file (and it should), you can enroll in two-factor auth with google, but be aware that it will affect the usage of your account. You can enroll here:
179 17 Brian Dickman
180 17 Brian Dickman
https://myaccount.google.com/security/signinoptions/two-step-verification/enroll-welcome
181 21 Dan Smith
182 17 Brian Dickman
With TFA enabled, you can add app-specific passwords, like one for mercurial:
183 17 Brian Dickman
184 17 Brian Dickman
https://security.google.com/settings/security/apppasswords
185 17 Brian Dickman
186 30 Nicolas Pike
Then add to your hgrc file - your gmail username, and the app-specific password.
187 27 Nicolas Pike
188 28 Nicolas Pike
<pre>
189 28 Nicolas Pike
[smtp]
190 27 Nicolas Pike
host = smtp.gmail.com
191 27 Nicolas Pike
port = 587
192 27 Nicolas Pike
tls = True
193 1 Dan Smith
username = myemailaddress@gmail.com
194 27 Nicolas Pike
password = appspecificpassword
195 28 Nicolas Pike
</pre>
196 27 Nicolas Pike
197 27 Nicolas Pike
and you should be all set.
198 3 Dan Smith
199 3 Dan Smith
h2. Patch Guidelines
200 1 Dan Smith
201 3 Dan Smith
h3. The Commit Message
202 14 Robert Terzi
203 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. An issue number from the issue tracking system must be included to tie the submitted patch to an open issue. For example:
204 3 Dan Smith
205 14 Robert Terzi
<pre>
206 3 Dan Smith
[uv5r] Add support for firmware >= 291 Fixes #123
207 3 Dan Smith
</pre>
208 3 Dan Smith
209 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.
210 24 Dan Smith
211 24 Dan Smith
If your first line is not completely self-explanatory (like the one above) then you should have a second paragraph explaining what is being changed and why, especially if it's not a straightforward "add support for XXX" type of patch.
212 3 Dan Smith
213 3 Dan Smith
h3. Scope
214 3 Dan Smith
215 3 Dan Smith
Guidelines:
216 3 Dan Smith
217 3 Dan Smith
 * Patches should be small and concise. Try to keep a single standing change to a single patch.
218 3 Dan Smith
 * Don't fix several bugs in a single patch, unless there is a technical reason to do so.
219 1 Dan Smith
 * Don't fix, cleanup, or change random whitespace in the patch unless that is the sole purpose of the patch.