2019-12-13 10:42:46 +01:00
|
|
|
:linkattrs:
|
2018-05-09 15:18:57 -07:00
|
|
|
= Gerrit Code Review: Developer Setup
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2019-12-10 18:01:31 +01:00
|
|
|
To build a developer instance, you'll need link:https://bazel.build/[Bazel,role=external,window=_blank] to
|
2020-01-29 18:02:53 +09:00
|
|
|
compile the code, preferably launched with link:https://github.com/bazelbuild/bazelisk[Bazelisk,role=external,window=_blank].
|
2013-05-10 15:34:02 +01:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
== Git Setup
|
|
|
|
|
2019-10-29 09:27:00 +01:00
|
|
|
[[clone]]
|
2019-05-07 19:13:00 +02:00
|
|
|
=== Getting the Source
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2009-12-16 11:32:39 -08:00
|
|
|
Create a new client workspace:
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2009-12-16 11:32:39 -08:00
|
|
|
----
|
2018-10-12 14:01:39 +09:00
|
|
|
git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
|
2009-12-16 11:32:39 -08:00
|
|
|
cd gerrit
|
|
|
|
----
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2019-05-03 11:47:51 +02:00
|
|
|
The `--recurse-submodules` option is needed on `git clone` to ensure that the
|
|
|
|
core plugins, which are included as git submodules, are also cloned.
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
=== Switching between branches
|
|
|
|
|
|
|
|
When using `git checkout` without `--recurse-submodules` to switch between
|
|
|
|
branches, submodule revisions are not altered, which can result in:
|
|
|
|
|
|
|
|
* Incorrect or unneeded plugin revisions.
|
|
|
|
* Missing plugins.
|
|
|
|
|
|
|
|
After you switch branches, ensure that you have the correct versions of
|
|
|
|
the submodules.
|
|
|
|
|
|
|
|
CAUTION: If you store Eclipse or IntelliJ project files in the Gerrit source
|
|
|
|
directories, do *_not_* run `git clean -fdx`. Doing so may remove untracked files and damage your project. For more information, see
|
2019-12-10 18:01:31 +01:00
|
|
|
link:https://git-scm.com/docs/git-clean[git-clean,role=external,window=_blank].
|
2019-05-07 19:13:00 +02:00
|
|
|
|
|
|
|
Run the following:
|
|
|
|
|
|
|
|
----
|
|
|
|
git submodule update
|
|
|
|
git clean -ffd
|
|
|
|
----
|
|
|
|
|
2016-11-25 10:54:30 +01:00
|
|
|
[[compile_project]]
|
2013-12-20 12:55:51 -08:00
|
|
|
== Compiling
|
2013-05-20 11:08:51 +09:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
For details, see <<dev-bazel#,Building with Bazel>>.
|
2013-12-13 15:03:02 +09:00
|
|
|
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
== Testing
|
2014-04-27 21:16:25 +02:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
[[tests]]
|
|
|
|
=== Running the acceptance tests
|
2016-11-25 10:54:30 +01:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
Gerrit contains acceptance tests that validate the Gerrit daemon via REST, SSH,
|
|
|
|
and the Git protocol.
|
2013-05-10 15:34:02 +01:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
A new review site is created for each test and the Gerrit daemon is
|
|
|
|
then started on that site. When the test is completed, the Gerrit daemon is
|
|
|
|
shut down.
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
For instructions on running the acceptance tests with Bazel,
|
|
|
|
see <<dev-bazel#tests,Running Unit Tests with Bazel>>.
|
2014-03-30 07:43:31 -07:00
|
|
|
|
2020-01-29 14:27:28 -05:00
|
|
|
[[e2e]]
|
|
|
|
=== End-to-end tests
|
|
|
|
|
2020-03-20 11:38:29 -04:00
|
|
|
<<dev-e2e-tests#,This document>> describes how `e2e` (load or functional) test
|
2020-03-24 08:38:25 +09:00
|
|
|
scenarios are implemented using link:https://gatling.io/[`Gatling`,role=external,window=_blank].
|
2020-01-29 14:27:28 -05:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
== Local server
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2009-12-16 11:32:39 -08:00
|
|
|
[[init]]
|
2019-05-07 19:13:00 +02:00
|
|
|
=== Site Initialization
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
After you compile the project <<compile_project,(above)>>, run the Gerrit
|
|
|
|
`init`
|
|
|
|
command to create a test site:
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2016-11-25 10:54:30 +01:00
|
|
|
----
|
2019-05-02 10:43:40 +02:00
|
|
|
export GERRIT_SITE=~/gerrit_testsite
|
2016-11-25 10:54:30 +01:00
|
|
|
$(bazel info output_base)/external/local_jdk/bin/java \
|
2019-05-02 10:43:40 +02:00
|
|
|
-jar bazel-bin/gerrit.war init --batch --dev -d $GERRIT_SITE
|
2016-11-25 10:54:30 +01:00
|
|
|
----
|
|
|
|
|
|
|
|
[[special_bazel_java_version]]
|
2018-05-09 15:18:57 -07:00
|
|
|
NOTE: You must use the same Java version that Bazel used for the build, which
|
|
|
|
is available at `$(bazel info output_base)/external/local_jdk/bin/java`.
|
|
|
|
|
2019-04-29 21:41:05 +02:00
|
|
|
This command takes two parameters:
|
2016-11-25 10:54:30 +01:00
|
|
|
|
2019-04-29 21:41:05 +02:00
|
|
|
* `--batch` assigns default values to several Gerrit configuration
|
|
|
|
options. To learn more about these options, see
|
|
|
|
link:config-gerrit.html[Configuration].
|
|
|
|
* `--dev` configures the Gerrit server to use the authentication
|
|
|
|
option, `DEVELOPMENT_BECOME_ANY_ACCOUNT`, which enables you to
|
|
|
|
switch between different users to explore how Gerrit works. To learn more
|
|
|
|
about setting up Gerrit for development, see
|
|
|
|
link:dev-readme.html[Gerrit Code Review: Developer Setup].
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
After initializing the test site, Gerrit starts serving in the background. A
|
|
|
|
web browser displays the Start page.
|
2009-06-04 10:05:03 -07:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
On the Start page, you can:
|
2016-10-12 11:24:06 -07:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
. Log in as the account you created during the initialization process.
|
|
|
|
. Register additional accounts.
|
|
|
|
. Create projects.
|
|
|
|
|
|
|
|
To shut down the daemon, run:
|
2009-06-04 10:05:03 -07:00
|
|
|
|
2009-12-16 11:32:39 -08:00
|
|
|
----
|
2019-05-02 10:43:40 +02:00
|
|
|
$GERRIT_SITE/bin/gerrit.sh stop
|
2009-12-16 11:32:39 -08:00
|
|
|
----
|
2009-01-09 11:55:47 -08:00
|
|
|
|
|
|
|
|
2016-10-12 11:24:06 -07:00
|
|
|
[[localdev]]
|
2019-05-07 19:13:00 +02:00
|
|
|
=== Working with the Local Server
|
2016-10-12 11:24:06 -07:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
To create more accounts on your development instance:
|
|
|
|
|
|
|
|
. Click 'become' in the upper right corner.
|
|
|
|
. Select 'Switch User'.
|
|
|
|
. Register a new account.
|
2019-01-22 10:36:23 +01:00
|
|
|
. link:user-upload.html#ssh[Configure your SSH key].
|
2016-10-12 11:24:06 -07:00
|
|
|
|
|
|
|
Use the `ssh` protocol to clone from and push to the local server. For
|
|
|
|
example, to clone a repository that you've created through the admin
|
|
|
|
interface, run:
|
|
|
|
|
|
|
|
----
|
|
|
|
git clone ssh://username@localhost:29418/projectname
|
|
|
|
----
|
|
|
|
|
2019-05-17 10:39:41 +02:00
|
|
|
To use the `HTTP` protocol, run:
|
|
|
|
|
|
|
|
----
|
|
|
|
git clone http://username@localhost:8080/projectname
|
|
|
|
----
|
|
|
|
|
|
|
|
The default password for user `admin` is `secret`. You can regenerate a
|
|
|
|
password in the UI under User Settings -- HTTP credentials. The password can be
|
|
|
|
stored locally to avoid retyping it:
|
|
|
|
|
|
|
|
----
|
|
|
|
git config --global credential.helper store
|
|
|
|
git pull
|
|
|
|
----
|
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
To create changes as users of Gerrit would, run:
|
2016-10-12 11:24:06 -07:00
|
|
|
|
|
|
|
----
|
|
|
|
git push origin HEAD:refs/for/master
|
|
|
|
----
|
|
|
|
|
2016-11-25 12:02:18 +01:00
|
|
|
[[run_daemon]]
|
2013-12-20 12:55:51 -08:00
|
|
|
=== Running the Daemon
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
The daemon can be launched directly from the build area, without
|
2009-12-16 11:32:39 -08:00
|
|
|
copying to the test site:
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2016-11-25 10:54:30 +01:00
|
|
|
----
|
|
|
|
$(bazel info output_base)/external/local_jdk/bin/java \
|
2019-05-02 10:43:40 +02:00
|
|
|
-jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE \
|
2017-01-19 15:26:42 +01:00
|
|
|
--console-log
|
2016-11-25 10:54:30 +01:00
|
|
|
----
|
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
NOTE: To learn why using `java -jar` isn't sufficient, see
|
|
|
|
<<special_bazel_java_version,this explanation>>.
|
2016-11-25 10:54:30 +01:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
To debug the Gerrit server of this test site:
|
|
|
|
|
|
|
|
. Open a debug port (such as port 5005). To do so, insert the following code
|
|
|
|
immediately after `-jar` in the previous command. To learn how to attach
|
|
|
|
IntelliJ, see <<dev-intellij#remote-debug,Debugging a remote Gerrit server>>.
|
2017-03-02 13:20:32 +01:00
|
|
|
|
|
|
|
----
|
|
|
|
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
|
|
|
|
----
|
|
|
|
|
2013-12-20 12:55:51 -08:00
|
|
|
=== Running the Daemon with Gerrit Inspector
|
2012-04-17 16:24:34 +00:00
|
|
|
|
|
|
|
link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable
|
2018-05-09 15:18:57 -07:00
|
|
|
environment you can use to inspect and modify the internal state of the system.
|
2012-04-17 16:24:34 +00:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
Gerrit Inspector appears on the system console whenever the system starts.
|
|
|
|
Leaving the Inspector shuts down the Gerrit instance.
|
2012-04-17 16:24:34 +00:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
To troubleshoot, the Inspector enables interactive work as well as running of
|
|
|
|
Python scripts.
|
2012-04-17 16:24:34 +00:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
To start the Inspector, add the '-s' option to the daemon start command:
|
2012-04-17 16:24:34 +00:00
|
|
|
|
2016-11-25 10:54:30 +01:00
|
|
|
----
|
|
|
|
$(bazel info output_base)/external/local_jdk/bin/java \
|
2019-05-02 10:43:40 +02:00
|
|
|
-jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE -s
|
2016-11-25 10:54:30 +01:00
|
|
|
----
|
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
NOTE: To learn why using `java -jar` isn't sufficient, see
|
|
|
|
<<special_bazel_java_version,this explanation>>.
|
2016-11-25 10:54:30 +01:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
Inspector examines Java libraries, loads the initialization scripts, and
|
|
|
|
starts a command line prompt on the console:
|
2012-04-17 16:24:34 +00:00
|
|
|
|
|
|
|
----
|
|
|
|
Welcome to the Gerrit Inspector
|
|
|
|
Enter help() to see the above again, EOF to quit and stop Gerrit
|
|
|
|
Jython 2.5.2 (Release_2_5_2:7206, Mar 2 2011, 23:12:06)
|
2018-05-09 15:18:57 -07:00
|
|
|
[OpenJDK 64-Bit Server VM (Sun Microsystems Inc.)] on java1.6.0 running for
|
|
|
|
Gerrit 2.3-rc0-163-g01967ef
|
2012-04-17 16:24:34 +00:00
|
|
|
>>>
|
|
|
|
----
|
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
When the Inspector is enabled, you can use Gerrit as usual and all
|
|
|
|
interfaces (including HTTP and SSH) are available.
|
2012-04-17 16:24:34 +00:00
|
|
|
|
2018-05-09 15:18:57 -07:00
|
|
|
CAUTION: When using the Inspector, be careful not to modify the internal state
|
|
|
|
of the system.
|
2009-01-09 11:55:47 -08:00
|
|
|
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
== Setup for backend developers
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
=== Configuring Eclipse
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
To use the Eclipse IDE for development, see
|
|
|
|
link:dev-eclipse.html[Eclipse Setup].
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
To configure the Eclipse workspace with Bazel, see
|
|
|
|
link:dev-bazel.html#eclipse[Eclipse integration with Bazel].
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2019-05-07 19:13:00 +02:00
|
|
|
=== Configuring IntelliJ IDEA
|
|
|
|
|
|
|
|
See <<dev-intellij#,IntelliJ Setup>> for details.
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2019-05-07 19:26:18 +02:00
|
|
|
== Setup for frontend developers
|
|
|
|
See link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui/README.md[Frontend Developer Setup].
|
|
|
|
|
2009-12-16 11:32:39 -08:00
|
|
|
|
2009-05-28 15:55:01 -07:00
|
|
|
GERRIT
|
|
|
|
------
|
|
|
|
Part of link:index.html[Gerrit Code Review]
|
2013-10-31 17:26:00 -07:00
|
|
|
|
|
|
|
SEARCHBOX
|
|
|
|
---------
|