diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..faaaa55 --- /dev/null +++ b/README.md @@ -0,0 +1,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? |