Add README.md

This is mostly written by Jukka, I re-arranged some things and moved it
over to markdown.

Change-Id: I25933ef1ebfda69b50c3c010c28b70714957a010
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Jukka Jokiniva <jukka.jokiniva@qt.io>
Reviewed-by: Orgad Shaneh <orgads@gmail.com>
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>

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?