blob: faaaa55e6dadd592d44f41ce8cba0626dcee6b6f (
plain)
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
|
# General
This plugin extends standard the Gerrit functionality to support the review flow at codereview.qt-project.org.
The main difference to the standard flow is that the final change merge is triggered by a CI backend. This is
achieved by:
* adding new statuses to the system: "staged" and "integrating"
* adding SSH command APIs for the CI
* adding REST APIs for status changes to be called from the Gerrit UI
* modifying the UI to support this all
There is also new status "deferred" which is similar to "abandoned".
Below the status transition diagram:
____________ _______ __________ _______________ __________
| DEFERRED | <-defer-- | NEW | ---stage--> | STAGED | --new build-> | INTEGRATING | --build approve-> | MERGED |
^ | --reopen-> ^ <-unstage-- | |
| | | | |
| | -------------------build reject---------------- |
| V ^ |
_____________ | |
| ABANDONED | -------------------build merge failed-----------
## UI Commands for a Change
Submit to Staging
* merges the change into the ref/staging/a_branch_name and updates the status to "staged".
Unstage
* updates change status back to "new" and rebuilds staging ref based on all changes in "staged" status.
Defer
* updates change status to "deferred".
Reopen
* updates change status back to new.
## SSH Command APIs
Ping:
* Just a ping API
* example: ssh -p 29418 admin@codereview.qt-project.org gerrit-plugin-qt-workflow ping
New Build
* creates ref/builds/abuildname from current staging ref and the staged changes are moved to "integrating" status.
* example: ssh -p 29418 anuser@codereview.qt-project.org gerrit-plugin-qt-workflow staging-new-build --staging-branch master --build-id b001 --project TestProject
Build Approve
* if result param is pass, merges build ref into target branch and the changes are moved to "merged" status.
* if result param is fail, moves the changes in the build back to "new" status. Staging ref is rebuild to remove the failed changes.
* example: ssh -p 29418 anuser@codereview.qt-project.org gerrit-plugin-qt-workflow staging-approve --branch master --build-id b001 --project TestProject --result pass
Rebuild Staging
* Staging ref is reseted to target branch and all changes in "Integrated" and "Staged" status are added to the staging ref.
* example: ssh -p 29418 anuser@codereview.qt-project.org gerrit-plugin-qt-workflow staging-rebuild --branch master --project TestProject
List Staging
* List changes between a ref and the destination branch
* example: ssh -p 29418 anuser@codereview.qt-project.org gerrit-plugin-qt-workflow staging-ls --branch refs/staging/master --destination master --project TestProject
## Development
The plugin contains two parts:
* qt-gerrit-ui-plugin.html extends the UI and it is a PolyGerrit plugin.
* gerrit-plugin-qt-workflow.jar extends the REST and SSH command APIs. It's type is gerrit-plugin-api.jar.
See:
* https://gerrit-review.googlesource.com/Documentation/dev-plugins.html
* https://gerrit-review.googlesource.com/Documentation/pg-plugin-dev.html
* https://gerrit-review.googlesource.com/Documentation/dev-readme.html
* https://gerrit-review.googlesource.com/Documentation/dev-bazel.html
Building the UI Plugin
* No need to build, it is all running on the client browser.
Building the Java Plugin
* have a gerrit checkout and clone the plugin to plugins/gerrit-plugin-qt-workflow (we should add it as submodule when it's done)
* run "bazel build plugins/gerrit-plugin-qt-workflow"
* the binary will be "bazel-genfiles/plugins/gerrit-plugin-qt-workflow/gerrit-plugin-qt-workflow.jar"
Building Gerrit
* run "bazel build release"
* copy binary file to the gerrit site directory: "cp bazel-bin/release.war thedir/bin/gerrit.war"
Working with the local development environment
* Setup database
https://codereview.qt-project.org/Documentation/install.html#createdb
* Init test site
https://gerrit-review.googlesource.com/Documentation/dev-readme.html#init
* Set access righs for test projects:
go: http://localhost:8080/admin/repos/All-Projects,access
allow admin/test users to create reference: refs/*
* Gerrit commands:
./bin/gerrit.sh start
./bin/gerrit.sh stop
./bin/gerrit.sh run
* web access
http://localhost:8080
* SSH API command examples:
ssh -p 29418 admin@localhost gerrit-plugin-qt-workflow ping
ssh -p 29418 admin@localhost gerrit-plugin-qt-workflow staging-new-build --staging-branch master --build-id b001 --project JustTest
ssh -p 29418 admin@localhost gerrit-plugin-qt-workflow staging-approve --branch master --build-id b001 --project JustTest --result pass
ssh -p 29418 admin@localhost gerrit stream-events
ssh -p 29418 admin@localhost gerrit index changes 17 26 27 28
* useful Git commands
git pull --recurse-submodules
git clone ssh://admin@localhost:29418/arepo.git
git push origin HEAD:refs/for/master
git fetch -f origin refs/staging/*:refs/staging/*
git fetch -f origin refs/builds/*:refs/builds/*
git fetch origin
git reset --hard origin/master
* Running tests:
bazel test --test_output=streamed //plugins/gerrit-plugin-qt-workflow:*
* Test coverage:
install genhtml tool, for example: brew install lcov
run: bazel coverage //plugins/gerrit-plugin-qt-workflow:*
cd plugins/gerrit-plugin-qt-workflow
./tools/coverage.sh thecoveragefile.dat
=> html report available at ./coverage/index.html
## Installation
Copy gerrit-plugin-qt-workflow.jar and qt-gerrit-ui-plugin.html to the gerrit site "plugins" directory.
NOTE that the plugin depends on the Gerrit internal APIs, so if Gerrit is upgraded to a new version the plugin
needs to be recompiled against the same version.
As of today the plugin requires custom patches on top of the Gerrit. So the Gerrit binary needs to be
rebuild with the patches. The plan is to upstream these changes.
Access rights:
* FIXME: Stage/Unstage requires push permission to refs/staging/* branch - we should instead have an explicit staging right
* Defer/Reopen requires same permissions as abandon
* CI needs the permission to created references (refs/builds/*), push to branches (refs/heads/*) and
force push to staging refs (refs/staging/*)
Copy static files into the site dir: cp gerrit-plugin-qt-workflow/static/* gerritsitedir/static/
## Open Items
* Events are needed for staged, integrating and deferred status changes
* There is currently no rights management for when to show the staging button
* In testing the staging branch was not created automatically
* Are email notifications needed for deferred, reopened status changes?
* automated tests for UI?
|
