1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
#!/bin/sh
usage () { echo Usage: `basename $0` '[-h|-u] [-r ref] [--] command...'; }
# Copyright (C) 2016 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
help () {
usage
# Example data:
[ "$LAST" ] || LAST=v5.9.0
[ "$NEXT" ] || NEXT=5.10
[ "$TASK" ] || TASK=QTBUG-5678
ME=`basename $0`
cat <<EOF
Run from the top-level (qt5) directory of a full Qt checkout with the
module-set of an imminent release. For API change review generation,
check out .gitmodules on the reference version, so as to use its list
of modules (and skip modules that were in preview back then). Give
this script a command to run in each module; the purpose of this
script is to run api-review-gen on each; but it also serves to prepare
for this and later to run a git push to send the results to Gerrit for
review. See examples below and output of ./api-review-gen -h for
further details.
Although this script can be used to run a general command in each
module, its selection of modules is specifically geared towards the
particular task of generating API change reviews, under the conditions
described above; a general module iterator might one day replace it,
but please don't try to evolve this into that.
Options:
-u
--usage Print simple usage summary (first line above) and exit.
-h
--help Print this help and exit.
-i
--ignored
Invert the selection on status, to get the modules that
would normally be ignored, but that otherwise would qualify
for review.
-r ref
--require ref
Limit to modules that have a specific branch or tag.
May be used repeatedly to require several refs.
-- End option processing.
Arguments:
command...
The command to run in each relevant module, along with its
arguments.
Several --require options may be used; for example, one for a prior
release tag, another for an imminent release branch. Note that, if a
relevant module is missing (not cloned), this script silently skips
it; you do need to have a suitable full work tree.
By way of example, here's the work-flow for producing an API change
review between $LAST and $NEXT to be tracked by Jira issue $TASK (you
can set LAST, NEXT and TASK in the environment to configure the
examples), assuming qtqa/scripts/api-review is in your PATH:
Get qt5 up to date, but with the old .gitmodules:
$ git checkout $NEXT && git pull --ff-only
$ git checkout $LAST -- .gitmodules
Check status of all relevant modules:
$ $ME git status
You'll need all your working trees clean before you proceed.
Get each potentially relevant module's origin up to date:
$ $ME git fetch origin
Make sure each has the new branch available to check out:
$ $ME -r origin/$NEXT \\
git fetch origin $NEXT:$NEXT '||' git pull --ff-only
Generate review branches (but see notes following):
$ $ME -r $LAST -r $NEXT api-review-gen -t $TASK $LAST $NEXT
Add a --amend before the -t in that to update review branches to
reflect changes in imminent release (e.g. fixes for an earlier round
of review) after updating $NEXT as above. If the $NEXT branch name
isn't the imminent release's version (e.g. if the release hasn't yet
branched out from dev), see the --release option to api-review-gen.
Examine residual diff (should all be boring):
$ $ME -r api-review-$LAST-$NEXT git diff -b -D
If any of that isn't boring, you can git add -p the relevant files
and git commit --amend to include the non-boring parts of the files.
In such a case, it is a good idea to work out why resetboring.py
thought it was boring and fix it, if possible, to avoid similar
errors in future.
When doing an amend, git fetch the currently live patch-set of the
review in each sub-module (sadly not something we can automate with
this script) and also git diff -b -D FETCH_HEAD HEAD - if others have
added files to the review (as can happen with private headers that
define QML API), they'll show up in this diff. You need to check such
files out on $NEXT and add them to the newly amended commit. You can
run resetboring.py (without --disclaim) to unstage any boring changes
to such files, before committing such additions.
Clear away residual diff (after verifying it's all boring):
$ $ME -r api-review-$LAST-$NEXT git reset --hard HEAD
Remove review branch where we committed nothing:
$ $ME -r api-review-$LAST-$NEXT \\
if git diff --quiet $LAST api-review-$LAST-$NEXT ';' \\
then git reset --hard HEAD '&&' \\
git checkout $NEXT '&&' \\
git branch -D api-review-$LAST-$NEXT ';' fi
Note the use of quoted shell metacharacters; $ME shall
eval the command, ensuring they do their proper job.
Now we must discard any modules that aren't part of the coming
release, for which we need the current .gitmodules rather than the
old one:
$ git checkout $NEXT -- .gitmodules
Clear review branches from any modules to be ignored:
$ $ME -i -r api-review-$LAST-$NEXT \\
git checkout $NEXT '&&' git branch -D api-review-$LAST-$NEXT
Examine changes (mostly interesting) to be reviewed:
$ $ME -r api-review-$LAST-$NEXT git log -p $LAST..
Push to gerrit:
$ $ME -r api-review-$LAST-$NEXT \\
git push gerrit HEAD:refs/for/$NEXT%topic=api-change-review-$NEXT
When $LAST has changed (only relevant when using a branch here),
rebase review branches onto it:
$ $ME -r api-review-$LAST-$NEXT git rebase $LAST api-review-$LAST-$NEXT
Note that all of the above presumes you have an up-to-date module set
checked out; if you have not run qt5/init-repository recently, it may
be prudent to do so before you start. Some modules may have been added
or changed status since you last ran it.
EOF
}
warn () { echo "$@" >&2; }
die () { warn "$@"; exit 1; }
banner () { echo; echo "====== $@ ======"; echo; }
# Convert each .gitmodules stanza into a single line:
modules () {
sed -e 's/^\[submodule/\v[submodule/' <.gitmodules | tr '\n\v' '\f\n'
echo
}
# Parse a single linearised stanza; discard if boring (or, when INVERT
# is set, if interesting), else extract its directory name:
INVERT=
vetcheck () {
# Can't return from within the while loop; piping input to it has
# made it a sub-shell. (That also precludes assigning any
# variables within the loop; values would be forgotten after.)
echo "$@" | tr '\f' '\n' | while read name op value
do
[ "$op" = '=' ] || continue
case "$name" in
status)
# No BC/SC promises in preview; and we
# don't care about obsolete or ignore:
case "$value" in
essential|addon|deprecated) [ -z "$INVERT" ] || echo no ;;
preview|obsolete|ignore) [ -n "$INVERT" ] || echo no ;;
*) warn "Unrecognized module status: $value (treated as active)"
[ -z "$INVERT" ] || echo no
;;
esac;;
# repotools has qt = false
qt) [ "$value" = false ] && echo no ;;
# non-versioned modules aren't relevant to us:
branch) [ "$value" = master ] && echo no ;;
esac
done
}
vet () {
# First pass: filter out modules we don't want:
if vetcheck "$@" | grep -q no
then return
fi
echo "$@" | grep -w 'status *= *' | \
tr '\f' '\n' | grep 'path *=' | cut -d = -f 2
}
# Re-echo a module if it has all required refs:
checkrefs () {
for ref in $REFS
# Use rev-parse --verify to test whether $ref exists in this repo:
do (cd "$1" && git rev-parse -q --verify "$ref^{commit}" >/dev/null 2>&1) || return
done
echo "$1"
}
# List the API-relevant modules:
relevant () {
# Select released Qt modules:
modules | while read stanza
do vet "$stanza"
done | while read path
# Only those with src/ and a sync.profile matter:
do if [ -d "$path/src" -a -f "$path/sync.profile" ]
# Filter on the desired refs (if any):
then checkrefs "$path"
fi
done
}
REFS=
while [ $# -gt 0 ]
do
case "$1" in
-u|--usage) usage; exit 0;;
-h|--help) help; exit 0;;
-i|--ignored) INVERT=yes; shift;;
-r|--require) REFS="$REFS $2"; shift 2;;
--) shift; break;;
-*) usage >&2; die "Unrecognised option: $1";;
*) break;;
esac
done
[ -e .gitmodules ] || die "I must be run in the top-level (qt5) directory"
if [ $# -eq 0 ]
then
usage >&2
die "You need to supply a command to run in each module !"
fi
relevant | while read dir
do (cd "$dir" && banner "$dir" && eval "$@") || warn "Failed ($?) in $dir: $@"
done
|
