DevelopersProcess » History » Version 37
Dan Smith, 02/12/2021 03:08 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 | 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 | |||
11 | 1 | Dan Smith | <pre> |
12 | [ui] |
||
13 | username = Joe Bob <joebob@gmail.com> |
||
14 | [extensions] |
||
15 | hgext.mq= |
||
16 | hgext.patchbomb= |
||
17 | 7 | Dan Smith | |
18 | 1 | Dan Smith | [email] |
19 | from = Joe Bob <joebob@gmail.com> |
||
20 | 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 | # bcc = Joe Bob <joebob@gmail.com> |
||
24 | 1 | Dan Smith | |
25 | [smtp] |
||
26 | 33 | Dan Smith | host = intrepid.danplanet.com |
27 | 16 | Tom Hayward | port = 587 |
28 | tls = True |
||
29 | 31 | Dan Smith | |
30 | [diff] |
||
31 | git = True |
||
32 | 1 | Dan Smith | </pre> |
33 | |||
34 | 13 | Dan Smith | h2. Getting the code |
35 | |||
36 | <pre> |
||
37 | hg clone http://d-rats.com/hg/chirp.hg |
||
38 | cd chirp.hg |
||
39 | </pre> |
||
40 | |||
41 | 3 | Dan Smith | h2. Bug Tracking |
42 | |||
43 | 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 | |||
45 | 1 | Dan Smith | h2. Submitting a patch |
46 | |||
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 | |||
49 | 37 | Dan Smith | You *must* include an Issue Number (#123) somewhere in the commit message to tie each patch to an issue for tracking purposes. Just putting it in the email message is not enough, as the issue reference must make it into Mercurial so that Redmine knows to link the issue with the commit. The merge and build tooling will refuse to import a patch that doesn't yield an issue number in the commit, which will result in your patch being rejected or manual work for the maintainer to do it for you. |
50 | 14 | Robert Terzi | |
51 | 2 | Dan Smith | h3. Making a change |
52 | |||
53 | 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 | |||
55 | <pre> |
||
56 | % hg status -mar |
||
57 | M chirp/ic2820.py |
||
58 | % hg diff |
||
59 | diff -r a132c837fd25 chirp/ic2820.py |
||
60 | --- a/chirp/ic2820.py Mon Dec 24 08:17:19 2012 -0800 |
||
61 | +++ b/chirp/ic2820.py Mon Dec 24 08:56:29 2012 -0800 |
||
62 | @@ -16,6 +16,8 @@ |
||
63 | from chirp import chirp_common, icf, util, directory |
||
64 | from chirp import bitwise |
||
65 | |||
66 | +# Just added a comment |
||
67 | + |
||
68 | MEM_FORMAT = """ |
||
69 | struct { |
||
70 | u32 freq; |
||
71 | </pre> |
||
72 | |||
73 | 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 | |||
75 | h3. Soft-committing a Change |
||
76 | |||
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 | <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 | |||
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 | |||
87 | <pre> |
||
88 | % hg add chirp/drivers/mynewdriver.py |
||
89 | % hg qnew -ef mypatch |
||
90 | </pre> |
||
91 | |||
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 | | 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 | |||
101 | |||
102 | h3. Working with Patches (mq mercurial extension) |
||
103 | |||
104 | The following commands demonstrate how the mq extension to hg can be used for managing patches. |
||
105 | |||
106 | | Command | Description | |
||
107 | | @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 | | @hg qpop@ | Remove it from the tree | |
||
110 | | @hg qapplied@ | This shows that no patches are applied | |
||
111 | | @hg qunapplied |
||
112 | mypatch@ | This shows that our patch is not applied | |
||
113 | | @hg qpush@ | This adds the patch back to the tree | |
||
114 | | @hg qapplied |
||
115 | mypatch@ | This shows that our patch is applied | |
||
116 | | @hg qpop@ | This removes it again | |
||
117 | | @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 | |||
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 | |||
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 | To run just a single driver's tests: |
||
139 | |||
140 | 1 | Dan Smith | <pre> |
141 | 26 | Dan Smith | % tox -e driver -- -d Icom_IC-2820H |
142 | 4 | Dan Smith | </pre> |
143 | |||
144 | To run just a specific test: |
||
145 | |||
146 | <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 | |||
152 | 35 | Daniel Clemmensen | While a test image may be any valid image file for your radio, be aware that this image file becomes part of the CHIRP test suite and will be distributed to anyone who downloads the CHIRP repository. Do not include an image with passwords, callsigns, or frequency lists that you do not wish to make public. A "factory reset" image is acceptable. |
153 | |||
154 | 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. |
155 | 15 | Robert Terzi | |
156 | 2 | Dan Smith | h3. Sending a change |
157 | |||
158 | 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: |
||
159 | |||
160 | <pre> |
||
161 | % hg export tip > add_comment.patch |
||
162 | </pre> |
||
163 | |||
164 | You can also configure the tool to email it directly, in which case you need only do: |
||
165 | |||
166 | <pre> |
||
167 | % hg email tip |
||
168 | 3 | Dan Smith | </pre> |
169 | |||
170 | You will be prompted for the destination address. |
||
171 | 22 | Dan Smith | |
172 | 17 | Brian Dickman | h2. Setting up *GMail* for patchbomb email |
173 | 23 | Aaron P | |
174 | h3. Without two factor identification |
||
175 | 21 | Dan Smith | |
176 | 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. |
177 | |||
178 | 34 | Daniel Clemmensen | However, Google will not allow mercurial (or other "less secure apps") to send email to it unless you change your gmail settings. This is described at: |
179 | https://support.google.com/accounts/answer/6010255 |
||
180 | |||
181 | 17 | Brian Dickman | h3. With two factor identification |
182 | 22 | Dan Smith | |
183 | 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: |
184 | |||
185 | https://myaccount.google.com/security/signinoptions/two-step-verification/enroll-welcome |
||
186 | 21 | Dan Smith | |
187 | 17 | Brian Dickman | With TFA enabled, you can add app-specific passwords, like one for mercurial: |
188 | |||
189 | https://security.google.com/settings/security/apppasswords |
||
190 | |||
191 | 30 | Nicolas Pike | Then add to your hgrc file - your gmail username, and the app-specific password. |
192 | 27 | Nicolas Pike | |
193 | 28 | Nicolas Pike | <pre> |
194 | [smtp] |
||
195 | 27 | Nicolas Pike | host = smtp.gmail.com |
196 | port = 587 |
||
197 | tls = True |
||
198 | 1 | Dan Smith | username = myemailaddress@gmail.com |
199 | 27 | Nicolas Pike | password = appspecificpassword |
200 | 28 | Nicolas Pike | </pre> |
201 | 27 | Nicolas Pike | |
202 | and you should be all set. |
||
203 | 3 | Dan Smith | |
204 | h2. Patch Guidelines |
||
205 | 1 | Dan Smith | |
206 | 3 | Dan Smith | h3. The Commit Message |
207 | 14 | Robert Terzi | |
208 | 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: |
209 | |||
210 | 14 | Robert Terzi | <pre> |
211 | 3 | Dan Smith | [uv5r] Add support for firmware >= 291 Fixes #123 |
212 | </pre> |
||
213 | |||
214 | 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. |
||
215 | 24 | Dan Smith | |
216 | 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. |
||
217 | 3 | Dan Smith | |
218 | h3. Scope |
||
219 | |||
220 | Guidelines: |
||
221 | |||
222 | * Patches should be small and concise. Try to keep a single standing change to a single patch. |
||
223 | * Don't fix several bugs in a single patch, unless there is a technical reason to do so. |
||
224 | 1 | Dan Smith | * Don't fix, cleanup, or change random whitespace in the patch unless that is the sole purpose of the patch. |