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
|
#!/bin/sh
usage () { echo Usage: `basename $0` '[-h|-u] [-r ref] [--] command...'; }
#############################################################################
##
## Copyright (C) 2016 The Qt Company Ltd.
## Contact: https://www.qt.io/licensing/
##
## This file is part of the release tools of the Qt Toolkit.
##
## $QT_BEGIN_LICENSE:LGPL$
## Commercial License Usage
## Licensees holding valid commercial Qt licenses may use this file in
## accordance with the commercial license agreement provided with the
## Software or, alternatively, in accordance with the terms contained in
## a written agreement between you and The Qt Company. For licensing terms
## and conditions see https://www.qt.io/terms-conditions. For further
## information use the contact form at https://www.qt.io/contact-us.
##
## GNU Lesser General Public License Usage
## Alternatively, this file may be used under the terms of the GNU Lesser
## General Public License version 3 as published by the Free Software
## Foundation and appearing in the file LICENSE.LGPL3 included in the
## packaging of this file. Please review the following information to
## ensure the GNU Lesser General Public License version 3 requirements
## will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
##
## GNU General Public License Usage
## Alternatively, this file may be used under the terms of the GNU
## General Public License version 2.0 or (at your option) the GNU General
## Public license version 3 or any later version approved by the KDE Free
## Qt Foundation. The licenses are as published by the Free Software
## Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
## included in the packaging of this file. Please review the following
## information to ensure the GNU General Public License requirements will
## be met: https://www.gnu.org/licenses/gpl-2.0.html and
## https://www.gnu.org/licenses/gpl-3.0.html.
##
## $QT_END_LICENSE$
##
#############################################################################
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.
-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:
$ $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.
Examine residual diff (should all be boring):
$ $ME -r api-review-$LAST-$NEXT git diff -b -D
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.
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
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
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, else extract
# its directory name:
vet () {
# First pass: filter out modules we don't want:
echo "$@" | tr '\f' '\n' | while read name op value
do
[ "$op" = '=' ] || continue
case "$name" in
# In dev, status is replaced by initrepo; but it's only
# given when true, so we can't filter on it here.
status)
# No BC/SC promises in preview; and we
# don't care about obsolete or ignore:
case "$value" in
essential|addon|deprecated) ;;
preview|obsolete|ignore) return ;;
esac;;
# repotools has qt = false
qt) [ "$value" = false ] && return ;;
# non-versioned modules aren't relevant to us:
branch) [ "$value" = master ] && return ;;
esac
done
# Because | while runs in a sub-shell, no variable assignment we
# make there survives to be used; so we need to re-scan to extract
# module paths:
echo "$@" | grep -w '\(status *= *\|initrepo *= *true\)' | \
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
}
[ -e .gitmodules ] || die "I must be run in the top-level (qt5) directory"
REFS=
while [ $# -gt 0 ]
do
case "$1" in
-u|--usage) usage; exit 0;;
-h|--help) help; exit 0;;
-r|--require) REFS="$REFS $2"; shift 2;;
--) shift; break;;
-*) usage >&2; die "Unrecognised option: $1";;
*) break;;
esac
done
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
|
