Left: | ||
Right: |
OLD | NEW |
---|---|
(Empty) | |
1 # Easy dependency updating | |
2 | |
3 | |
4 | |
5 ## Introduction | |
6 | |
7 This program is meant to ease up the process of gathering information / | |
kzar
2017/11/13 15:20:46
Nit: I think this reads better without the "up".
tlucas
2017/11/20 15:24:43
Done.
| |
8 preparing an issue on issues.adblockplus.org, in order to update a given | |
9 dependency. | |
10 | |
11 You can run this programm to get a list of potentially included changes | |
12 (represented by their commit messages), you can create a unified diff of all | |
kzar
2017/11/13 15:20:46
Nit: I think this would read better if it were spl
kzar
2017/11/13 15:20:46
Nit: Typo "program".
tlucas
2017/11/20 15:24:43
Done.
| |
13 potentially included changes or you can create an issue body, which is supposed | |
14 to be filed on https://issues.adblockplus.org. | |
15 | |
16 Since there won't be any way to bridge submodules / subrepositories between | |
17 Git and Mercurial any time soon, we will stay dependent on a manual approach | |
18 for mirroring these ourselves. | |
19 | |
20 ## Requirements | |
21 | |
22 - [Python 2.7](https://www.python.org/download/releases/2.7/) | |
23 - [Git](https://git-scm.com/) | |
24 - [Mercurial](https://www.mercurial-scm.org/) | |
25 | |
26 _(Please note, as soon as https://hg.adblockplus.org/buildtools/file/tip/ensure_ dependencies.py | |
27 is made Python 3.* compatible, the requirement for Python 2.7.* will be removed. )_ | |
28 | |
29 ## Compatibility | |
30 | |
31 This program runs with both Python 2.7.* and Python 3.*. | |
32 | |
33 ## Installation | |
34 | |
35 Execute setup.py: | |
36 ``` | |
37 $ python setup.py install | |
38 ``` | |
39 | |
40 _Please note: setup.py will additionally install | |
41 [jinja2](http://jinja.pocoo.org/docs/2.9/) on your machine._ | |
42 | |
43 ## Limitations | |
44 | |
45 Mainly due to humans being involved in reporting issues, there is no guarantee | |
46 that looking up integration notes will find everything that is needed to be | |
47 done, in order to update to a new revision. | |
48 | |
49 ## Running the programm | |
50 | |
51 Simply call the executable inside a repository which as dependencies. | |
52 A few examples: | |
53 | |
54 ### Show a list of changes between the current revision and the remote master fo r adblockpluscore | |
55 | |
56 ``` | |
57 $ depup changes adblockpluscore | |
58 ``` | |
59 | |
60 Result: | |
61 | |
62 ``` | |
63 ( dbfc37143497 ) : Noissue - Fix the escaping of '{' and '}' in CSS selectors (b y Hubert Figuière) | |
64 ( 1bb277740973 ) : Issue 5160 - Alias new class names and properties. (by Hubert Figuière) | |
65 ( 280efb445cc1 ) : Issue 5147 - Invalidate wrapper on delete (by Hubert Figuière ) | |
66 | |
67 ``` | |
68 | |
69 ### Generate a bare issue body for updating to the local master (-r master), but explicitly skip any mirroring (-s) | |
kzar
2017/11/13 15:20:46
Nit: Might be clearer if you clarify what mirrorin
tlucas
2017/11/20 15:24:42
Nice idea, done.
| |
70 | |
71 ``` | |
72 $ depup issue adblockpluscore -r master -s | |
73 ``` | |
74 | |
75 Result: | |
76 | |
77 ``` | |
78 === Background === | |
79 | |
80 CHANGE ME! | |
81 | |
82 === Included changes in `adblockpluscore` === | |
83 The list of changes imported by this is: | |
84 [[TicketQuery(id=5728&id=5773&id=5797&id=5735,order=id,desc=1,format=table,col=s ummary|component)]] | |
85 | |
86 || [https://hg.adblockplus.org/adblockpluscore/rev/dbfc37143497 dbfc37143497] || Noissue - Fix the escaping of '{' and '}' in CSS selectors || Hubert Figuière | | | |
87 || [https://hg.adblockplus.org/adblockpluscore/rev/b21bddce2678 b21bddce2678] || Noissue - Fixed typo with getLocalizedTexts function || Dave Barker || | |
88 || [https://hg.adblockplus.org/adblockpluscore/rev/a1b481e7d728 a1b481e7d728] || Noissue - Updated recommended subscriptions || Wladimir Palant || | |
89 || [https://hg.adblockplus.org/adblockpluscore/rev/fb758f96f7bb fb758f96f7bb] || Noissue - rename variable 'ret' to more meaningful 'filter' in lib/filterClasse s.js || Sergei Zabolotskikh || | |
90 | |
91 | |
92 === What to change === | |
93 Update the `adblockpluscore` dependency to: | |
94 | |
95 || **mercurial** || **git** || | |
96 || dbfc37143497 || NO MIRROR || | |
97 | |
98 === Integration Notes === | |
99 | |
100 CHANGE ME! | |
101 | |
102 === Hints for testers === | |
103 | |
104 CHANGE ME! | |
105 ``` | |
106 | |
107 ### Print information on the last 5 commits (-r HEAD~5) and lookup possible "Int egration Notes" for those (-l) | |
108 | |
109 ``` | |
110 (gitrepo)$ depup changes adblockpluscore -r HEAD~5 -l | |
111 ``` | |
112 | |
113 Result: | |
114 ``` | |
115 WARNING: you are trying to downgrade the dependency! | |
116 Integration notes found: https://issues.adblockplus.org/ticket/5735 | |
117 ( 2b57122 ) : Noissue - Fixed typo with getLocalizedTexts function Review: https ://codereview.adblockplus.org/29567746/ (by Dave Barker) | |
118 ( 662ce93 ) : Noissue - Updated recommended subscriptions (by Wladimir Palant) | |
119 ( 0591517 ) : Issue 5773 - use ES6 for stylesheets and cssRules. (by Hubert Figu ière) | |
120 ( 991b43c ) : Issue 5797 - Removed obsolete arguments from ElemHideEmulation con structor (by Sebastian Noack) | |
121 ( e533ded ) : Issue 5735 - Use JS Map instead of Object for matcher properties f ilterByKeyword and keywordByFilter (by Sergei Zabolotskikh) | |
122 ``` | |
123 | |
124 ### Generate a unified diff for the changes to buildtools @ remote master | |
125 ``` | |
126 $ depup diff buildtools | |
127 ``` | |
128 | |
129 Result: | |
130 ``` | |
131 diff --git a/.gitignore b/.gitignore | |
132 index 4090c27..5832582 100644 | |
133 --- a/.gitignore | |
134 +++ b/.gitignore | |
135 @@ -1,3 +1,6 @@ | |
136 *.pyc | |
137 *.pyo | |
138 /.tox | |
139 +/.cache | |
140 +.coverage | |
141 | |
142 ... | |
143 ... | |
144 ``` | |
145 | |
146 ## Help | |
147 | |
148 Depup comes with an integrated help page for each subcommand. The full pages: | |
149 | |
150 ### Root | |
151 | |
152 ``` | |
153 usage: depup [-h] {diff,issue,changes} ... | |
154 | |
155 Prepare a dependency update. | |
156 | |
157 This script executes the automatable work which needs to be done for a | |
158 dependency update and provides additional information, i.e. a complete | |
159 diff of imported changes, as well as related integration notes. | |
160 | |
161 optional arguments: | |
162 -h, --help show this help message and exit | |
163 | |
164 Subcommands: | |
165 {diff,issue,changes} Required, the actual command to be executed. Execute | |
166 run "<subcommand> -h" for more information. | |
167 | |
168 ``` | |
169 | |
170 ### diff | |
171 | |
172 ``` | |
173 usage: depup diff [-h] [-r NEW_REVISION] [-f FILENAME] [-l] [-s] | |
174 [-m LOCAL_MIRROR] [-n UNIFIED_LINES] | |
175 dependency | |
176 | |
177 optional arguments: | |
178 -h, --help show this help message and exit | |
179 -n UNIFIED_LINES, --n-context-lines UNIFIED_LINES | |
180 Number of unified context lines to be added to the | |
181 diff. Defaults to 16 (Used only with -d/--diff). | |
182 | |
183 Shared options: | |
184 dependency The dependency to be updated, as specified in the | |
185 dependencies file. | |
186 -r NEW_REVISION, --revision NEW_REVISION | |
187 The revision to update to. Defaults to the remote | |
188 master bookmark/branch. Must be accessible by the | |
189 dependency's vcs. | |
190 -f FILENAME, --filename FILENAME | |
191 When specified, write the subcommand's output to the | |
192 given file, rather than to STDOUT. | |
193 -l, --lookup-integration-notes | |
194 Search https://issues.adblockplus.org for integration | |
195 notes associated with the included issue IDs. The | |
196 results are written to STDERR. CAUTION: This is a very | |
197 network heavy operation. | |
198 -s, --skip-mirror Do not use any mirror. | |
199 -m LOCAL_MIRROR, --mirrored-repository LOCAL_MIRROR | |
200 Path to the local copy of a mirrored repository. Used | |
201 to fetch the corresponding hash. If not given, the | |
202 source parsed from the dependencies file is used. | |
203 | |
204 ``` | |
205 | |
206 ### changes | |
207 | |
208 ``` | |
209 usage: depup changes [-h] [-r NEW_REVISION] [-f FILENAME] [-l] [-s] | |
210 [-m LOCAL_MIRROR] | |
211 dependency | |
212 | |
213 optional arguments: | |
214 -h, --help show this help message and exit | |
215 | |
216 Shared options: | |
217 dependency The dependency to be updated, as specified in the | |
218 dependencies file. | |
219 -r NEW_REVISION, --revision NEW_REVISION | |
220 The revision to update to. Defaults to the remote | |
221 master bookmark/branch. Must be accessible by the | |
222 dependency's vcs. | |
223 -f FILENAME, --filename FILENAME | |
224 When specified, write the subcommand's output to the | |
225 given file, rather than to STDOUT. | |
226 -l, --lookup-integration-notes | |
227 Search https://issues.adblockplus.org for integration | |
228 notes associated with the included issue IDs. The | |
229 results are written to STDERR. CAUTION: This is a very | |
230 network heavy operation. | |
231 -s, --skip-mirror Do not use any mirror. | |
232 -m LOCAL_MIRROR, --mirrored-repository LOCAL_MIRROR | |
233 Path to the local copy of a mirrored repository. Used | |
234 to fetch the corresponding hash. If not given, the | |
235 source parsed from the dependencies file is used. | |
236 | |
237 ``` | |
238 | |
239 ### issue | |
240 | |
241 ``` | |
242 usage: depup issue [-h] [-r NEW_REVISION] [-f FILENAME] [-l] [-s] | |
243 [-m LOCAL_MIRROR] [-t TMPL_PATH] | |
244 dependency | |
245 | |
246 optional arguments: | |
247 -h, --help show this help message and exit | |
248 -t TMPL_PATH, --template TMPL_PATH | |
249 The template to use. Defaults to the provided | |
250 default.trac (Used only with -i/--issue). | |
251 | |
252 Shared options: | |
253 dependency The dependency to be updated, as specified in the | |
254 dependencies file. | |
255 -r NEW_REVISION, --revision NEW_REVISION | |
256 The revision to update to. Defaults to the remote | |
257 master bookmark/branch. Must be accessible by the | |
258 dependency's vcs. | |
259 -f FILENAME, --filename FILENAME | |
260 When specified, write the subcommand's output to the | |
261 given file, rather than to STDOUT. | |
262 -l, --lookup-integration-notes | |
263 Search https://issues.adblockplus.org for integration | |
264 notes associated with the included issue IDs. The | |
265 results are written to STDERR. CAUTION: This is a very | |
266 network heavy operation. | |
267 -s, --skip-mirror Do not use any mirror. | |
268 -m LOCAL_MIRROR, --mirrored-repository LOCAL_MIRROR | |
269 Path to the local copy of a mirrored repository. Used | |
270 to fetch the corresponding hash. If not given, the | |
271 source parsed from the dependencies file is used. | |
272 | |
273 ``` | |
274 | |
275 ## Templating | |
276 | |
277 You can provide your own template, which can be rendered with all available info rmation. The default template renders as shown in the above example. | |
278 | |
279 There are at any time these values exposed to the template: | |
280 | |
281 - `repository` - the repository to update (equals the positional argument of dep up). | |
282 - `raw_changes` - the unparsed but mirrored list of changes (if existing, the it em at index 0 is the revision to update to), each item containing the following key/value pairs: | |
283 * `author` - the author of the commit. | |
284 * `message` - the commit message, stripped to the first line. | |
285 * `date` - The commit date, in the rfc822 format. | |
286 * `git_hash` - the git hash of the commit, (mirrored if root VCS is mercurial, 'NO MIRROR' if mirroring was skipped) | |
287 * `git_url` - the revisions' url @ www.github.com | |
288 * `hg_hash` - the mercurial hash of the commit, (mirrored if root VCS is git, 'NO MIRROR' if mirroring was skipped) | |
289 * `hg_url` - the revisions url @ hg.adblockplus.org | |
290 - `issue_ids` - A list of encountered Issue ids or an empty array. | |
291 - `noissues` - Changes which could not be associated with an issue id. Either an empty array, or a list of dictionaries, each containing the same key/value pair s as `raw_changes` | |
292 - `hg_hash` - the mercurial hash for the new revision ('NO MIRROR' if mercurial is the mirror's vcs and mirroring is skipped) | |
293 - `git_hash` the git hash for the new revision ('NO MIRROR' if git is the mirror 's vcs and mirroring is skipped) | |
294 | |
295 For more information, please consult [the jinja2 documentation](http://jinja.poc oo.org/docs/2.9/). | |
296 | |
297 ### Example template | |
298 | |
299 The following template generates an issue body, from which the line in "What to change" | |
300 can be copied to the dependencies file. | |
301 | |
302 Additionally, the hashes in the "What to change" section are hyperlinks to | |
303 their respective hosts. | |
304 | |
305 ``` | |
306 SUBJECT: | |
307 Update {{ repository }} dependency to {{ hg_hash }} | |
308 | |
309 === Background === | |
310 | |
311 CHANGE ME! | |
312 | |
313 === Included changes in `{{ repository }}` === | |
314 The list of changes imported by this is: | |
315 [[TicketQuery({%- for issue_id in issue_ids -%} | |
316 id={{ issue_id }}{%- if not loop.last -%}&{%- endif -%} | |
317 {%- endfor -%} | |
318 ,order=id,desc=1,format=table,col=summary|component)]] | |
319 | |
320 {% for change in noissues -%} | |
321 || [{{ change.hg_url }} {{ change.hg_hash }}] || {{ change.message }} || {{ chan ge.author }} || | |
322 {% endfor %} | |
323 | |
324 === What to change === | |
325 Update the `{{ repository }}` dependency to: | |
326 | |
327 {{ repository }} = {{ repository }} hg:[{{ raw_changes[0].hg_url }} {{ raw_chang es[0].hg_hash }}] git:[{{ raw_changes[0].git_url }} {{ raw_changes[0].git_hash } }] | |
328 | |
329 || **mercurial** || **git** || | |
330 || {{ hg_hash }} || {{ git_hash }} || | |
331 | |
332 === Integration Notes === | |
333 | |
334 CHANGE ME! | |
335 | |
336 === Hints for testers === | |
337 | |
338 CHANGE ME! | |
339 ``` | |
OLD | NEW |