opendev/gerrit
Code Issues Proposed changes

Copy edits to dev-readme.txt, install.txt, and linux-quickstart.txt

Browse Source 
Change-Id: Ifdd4cee178a70f216bfae5106d1ef92fad7d32d1
This commit is contained in:
Janet Davies 2018-05-09 15:18:57 -07:00
parent 49b63e0313
commit 0c1a621540
3 changed files with 142 additions and 194 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
Documentation/dev-readme.txt
View File

@ -1,9 +1,7 @@
= Gerrit Code Review - Developer Setup
Google Bazel is needed to compile the code, and an SQL database to
house the review metadata. H2 is recommended for development
databases, as it requires no external server process.
= Gerrit Code Review: Developer Setup
To build a developer instance, you'll need link:https://bazel.build/[Bazel] to
compile the code.
== Getting the Source
@ -21,59 +19,39 @@ cloned.
[[compile_project]]
== Compiling
Please refer to <<dev-bazel#,Building with Bazel>>.
== Switching between branches
When switching between branches with `git checkout`, be aware that
submodule revisions are not altered. This may result in the wrong
plugin revisions being present, unneeded plugins being present, or
expected plugins being missing.
After switching branches, make sure the submodules are at the correct
revisions for the new branch with the commands:
----
git submodule update
git clean -fdx
----
CAUTION: If you decide to store your Eclipse/IntelliJ project files in the
Gerrit source directories, executing `git clean -fdx` will remove them and hence
screw up your project.
For details, see <<dev-bazel#,Building with Bazel>>.
== Configuring Eclipse
To use the Eclipse IDE for development, please see
To use the Eclipse IDE for development, see
link:dev-eclipse.html[Eclipse Setup].
For details on how to configure the Eclipse workspace with Bazel,
refer to: link:dev-bazel.html#eclipse[Eclipse integration with Bazel].
To configure the Eclipse workspace with Bazel, see
link:dev-bazel.html#eclipse[Eclipse integration with Bazel].
== Configuring IntelliJ IDEA
Please refer to <<dev-intellij#,IntelliJ Setup>> for detailed
instructions.
See <<dev-intellij#,IntelliJ Setup>> for details.
== Mac OS X
== MacOS
On Mac OS X ensure "Java For Mac OS X 10.5 Update 4" (or later) has
been installed, and that `JAVA_HOME` is set to the
On MacOS, ensure that "Java for MacOS X 10.5 Update 4" (or higher) is installed
and that `JAVA_HOME` is set to the
link:install.html#Requirements[required Java version].
Java installations can typically be found in
"/System/Library/Frameworks/JavaVM.framework/Versions".
You can check the installed Java version by running `java -version` in
the terminal.
To check the installed version of Java, open a terminal window and run:
`java -version`
[[init]]
== Site Initialization
After compiling <<compile_project,(above)>>, run Gerrit's 'init' command to
create a testing site for development use:
After you compile the project <<compile_project,(above)>>, run the Gerrit
`init`
command to create a test site:
----
$(bazel info output_base)/external/local_jdk/bin/java \
@ -81,24 +59,26 @@ create a testing site for development use:
----
[[special_bazel_java_version]]
NOTE: You must use the same Java version that Bazel used for the build.
This Java version is available at
`$(bazel info output_base)/external/local_jdk/bin/java`.
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`.
During initialization, make two changes to the default settings:
During initialization, change two settings from the defaults:
* Change the listen addresses from '*' to 'localhost' to prevent outside
connections from contacting the development instance; and
* Change the auth type from 'OPENID' to 'DEVELOPMENT_BECOME_ANY_ACCOUNT' to
allow yourself to create and act as arbitrary test accounts on your
development instance.
* To ensure the development instance is not externally accessible, change the
listen addresses from '*' to 'localhost'.
* To allow yourself to create and act as arbitrary test accounts on your
development instance, change the auth type from 'OPENID' to 'DEVELOPMENT_BECOME_ANY_ACCOUNT'.
Continue through init until it completes. The daemon will automatically start in
the background and a web browser will launch to the start page. From here you
can sign in as the account created during init, register additional accounts,
create projects, and more.
After initializing the test site, Gerrit starts serving in the background. A
web browser displays the Start page.
When you want to shut down the daemon, simply run:
On the Start page, you can:
. Log in as the account you created during the initialization process.
. Register additional accounts.
. Create projects.
To shut down the daemon, run:
----
../gerrit_testsite/bin/gerrit.sh stop
@ -108,9 +88,11 @@ When you want to shut down the daemon, simply run:
[[localdev]]
== Working with the Local Server
If you need to create additional accounts on your development instance, click
'become' in the upper right corner, select 'Switch User', and then register
a new account.
To create more accounts on your development instance:
. Click 'become' in the upper right corner.
. Select 'Switch User'.
. Register a new account.
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
@ -120,34 +102,31 @@ interface, run:
git clone ssh://username@localhost:29418/projectname
----
Then you'll be able to create changes the same way users do, with
To create changes as users of Gerrit would, run:
----
git push origin HEAD:refs/for/master
----
== Testing
[[tests]]
=== Running the Acceptance Tests
=== Running the acceptance tests
Gerrit has a set of integration tests that test the Gerrit daemon via
REST, SSH and the git protocol.
Gerrit contains acceptance tests that validate the Gerrit daemon via REST, SSH,
and the Git protocol.
A new review site is created for each test and the Gerrit daemon is
started on that site. When the test has finished the Gerrit daemon is
shutdown.
then started on that site. When the test is completed, the Gerrit daemon is
shut down.
For instructions on running the integration tests with Bazel,
please refer to: <<dev-bazel#tests,Running Unit Tests with Bazel>>.
For instructions on running the acceptance tests with Bazel,
see <<dev-bazel#tests,Running Unit Tests with Bazel>>.
[[run_daemon]]
=== Running the Daemon
The daemon can be directly launched from the build area, without
The daemon can be launched directly from the build area, without
copying to the test site:
----
@ -156,133 +135,101 @@ copying to the test site:
--console-log
----
NOTE: Please refer to <<special_bazel_java_version,this explanation>>
for details why using `java -jar` isn't sufficient.
NOTE: To learn why using `java -jar` isn't sufficient, see
<<special_bazel_java_version,this explanation>>.
If you want to debug the Gerrit server of this test site, you can open a debug
port (for example port 5005) by inserting
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>>.
----
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
----
directly after `-jar` of the previous command. Please refer to
<<dev-intellij#remote-debug,Debugging a remote Gerrit server>> for instructions
of how to attach IntelliJ.
=== Running the Daemon with Gerrit Inspector
link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable
environment to inspect and modify internal state of the system.
environment you can use to inspect and modify the internal state of the system.
This environment is available on the system console after
the system starts. Leaving the Inspector will shutdown the Gerrit
instance.
Gerrit Inspector appears on the system console whenever the system starts.
Leaving the Inspector shuts down the Gerrit instance.
The environment allows interactive work as well as running of
Python scripts for troubleshooting.
To troubleshoot, the Inspector enables interactive work as well as running of
Python scripts.
Gerrit Inspect can be started by adding '-s' option to the
command used to launch the daemon:
To start the Inspector, add the '-s' option to the daemon start command:
----
$(bazel info output_base)/external/local_jdk/bin/java \
-jar bazel-bin/gerrit.war daemon -d ../gerrit_testsite -s
----
NOTE: Please refer to <<special_bazel_java_version,this explanation>>
for details why using `java -jar` isn't sufficient.
NOTE: To learn why using `java -jar` isn't sufficient, see
<<special_bazel_java_version,this explanation>>.
Gerrit Inspector examines Java libraries first, then loads
its initialization scripts and then starts a command line
prompt on the console:
Inspector examines Java libraries, loads the initialization scripts, and
starts a command line prompt on the console:
----
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)
[OpenJDK 64-Bit Server VM (Sun Microsystems Inc.)] on java1.6.0 running for Gerrit 2.3-rc0-163-g01967ef
[OpenJDK 64-Bit Server VM (Sun Microsystems Inc.)] on java1.6.0 running for
Gerrit 2.3-rc0-163-g01967ef
>>>
----
With the Inspector enabled Gerrit can be used normally and all
interfaces (HTTP, SSH etc.) are available.
When the Inspector is enabled, you can use Gerrit as usual and all
interfaces (including HTTP and SSH) are available.
Care must be taken not to modify internal state of the system
when using the Inspector.
CAUTION: When using the Inspector, be careful not to modify the internal state
of the system.
=== Querying the Database
=== Querying the database
The embedded H2 database can be queried and updated from the
command line. If the daemon is not currently running:
The embedded H2 database can be queried and updated from the command line. If
the daemon is not running, run:
----
$(bazel info output_base)/external/local_jdk/bin/java \
-jar bazel-bin/gerrit.war gsql -d ../gerrit_testsite -s
----
NOTE: Please refer to <<special_bazel_java_version,this explanation>>
for details why using `java -jar` isn't sufficient.
NOTE: To learn why using `java -jar` isn't sufficient, see
<<special_bazel_java_version,this explanation>>.
Or, if it is running and the database is in use, connect over SSH
using an administrator user account:
Alternatively, if the daemon is running and the database is in use, use an
administrator user account to connect over SSH:
----
ssh -p 29418 user@localhost gerrit gsql
----
[[debug-javascript]]
=== Debugging JavaScript
== Switching between branches
When debugging browser specific issues add `?dbg=1` to the URL so the
resulting JavaScript more closely matches the Java sources. The debug
pages use the GWT pretty format, where function and variable names
match the Java sources.
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
link:https://git-scm.com/docs/git-clean[git-clean].
Run the following:
----
http://localhost:8080/?dbg=1
git submodule update
git clean -ffd
----
== Client-Server RPC
The client-server RPC implementation is gwtjsonrpc, not the stock RPC
system that comes with GWT. This buys us automatic XSRF protection.
It also makes all of the messages readable and writable by any JSON
implementation, facilitating "mashups" and 3rd party clients.
The programming API is virtually identical, except service interfaces
extend RemoteJsonService instead of RemoteService.
== Why GWT?
We like it. Plus we can write Java code once and run it both in
the browser and on the server side.
== External Links
Google Web Toolkit:
* http://www.gwtproject.org/download.html[Download]
Apache SSHD:
* http://mina.apache.org/sshd/[SSHD]
H2:
* http://www.h2database.com/[H2]
* http://www.h2database.com/html/grammar.html[SQL Reference]
PostgreSQL:
* http://www.postgresql.org/download/[Download]
* http://www.postgresql.org/docs/[Documentation]
GERRIT
------
Part of link:index.html[Gerrit Code Review]

14
Documentation/install.txt
View File

@ -1,17 +1,19 @@
= Gerrit Code Review - Standalone Daemon Installation Guide
[[requirements]]
== Requirements
To run the Gerrit service, the following requirements must be met on
the host:
[[prerequisites]]
== Prerequisites
To run the Gerrit service, the following requirement must be met on the host:
* JRE, minimum version 1.8 http://www.oracle.com/technetwork/java/javase/downloads/index.html[Download]
You'll also need an SQL database to house the review metadata. You have the
choice of either using the embedded H2 or to host your own MySQL or PostgreSQL.
By default, Gerrit uses link:note-db.html[NoteDB] as the storage backend. (If
desired, you can _optionally_ use an external database such as MySQL or
PostgreSQL.)
[[cryptography]]
== Configure Java for Strong Cryptography
Support for extra strength cryptographic ciphers: _AES128CTR_, _AES256CTR_,
_ARCFOUR256_, and _ARCFOUR128_ can be enabled by downloading the _Java
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files_

81
Documentation/linux-quickstart.txt
View File

@ -1,64 +1,63 @@
= Quickstart for Installing Gerrit on Linux
This quickstart shows you how to install Gerrit on a Linux machine.
This content explains how to install a basic instance of Gerrit on a Linux
machine.
[NOTE]
====
The installation steps provided in this quickstart are for
demonstration purposes only. They are not intended for use in a production
environment.
This quickstart is provided for demonstration purposes only. The Gerrit instance
they install must not be used in a production environment.
For a more detailed installation guide, see
Instead, to install a Gerrit production environment, see
link:install.html[Standalone Daemon Installation Guide].
====
== Before you begin
== Before you start
To complete this quickstart, you need:
Be sure you have:
. A Unix-based server such as any of the Linux flavors or BSD.
. Java SE Runtime Environment version 1.8 or later.
. A Unix-based server, including any Linux flavor, MacOS, or Berkeley Software
Distribution (BSD).
. Java SE Runtime Environment 1.8 (or higher).
== Download Gerrit
From the Linux machine on which you want to install Gerrit:
. Open a terminal window.
. Download the Gerrit archive. See
link:https://gerrit-releases.storage.googleapis.com/index.html[Gerrit Code
Review - Releases] for a list of available archives.
. Download the desired Gerrit archive.
The steps in this quickstart used Gerrrit 2.14.2, which you can download using
a command such as:
To view previous archives, see
link:https://gerrit-releases.storage.googleapis.com/index.html[Gerrit Code Review: Releases]. The steps below install Gerrit 2.15.1:
....
wget https://www.gerritcodereview.com/download/gerrit-2.14.2.war
wget https://www.gerritcodereview.com/download/gerrit-2.15.1.war
....
NOTE: If you want to build and install Gerrit from the source files, see
link:dev-readme.html[Developer Setup].
NOTE: To build and install Gerrit from the source files, see
link:dev-readme.html[Gerrit Code Review: Developer Setup].
== Install and initialize Gerrit
From the command line, type the following:
From the command line, enter:
....
java -jar gerrit*.war init --batch --dev -d ~/gerrit_testsite
....
The preceding command uses two parameters:
This command takes two parameters:
* `--batch`. This parameter assigns default values to a variety of Gerrit
configuration options. To learn more about these configuration options, see
link:config-gerrit.html[Configuration].
* `--dev`. This parameter configures the server to use the authentication
option, `DEVELOPMENT_BECOME_ANY_ACCOUNT`. This authentication type makes it
easy for 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[Developer Setup].
* `--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].
This command displays a number of messages in the terminal window. The following
is an example of these messages:
While this command executes, status messages are displayed in the terminal
window. For example:
....
Generating SSH host key ... rsa(simple)... done
@ -67,14 +66,15 @@ Executing /home/gerrit/gerrit_testsite/bin/gerrit.sh start
Starting Gerrit Code Review: OK
....
The last message you should see is `Starting Gerrit Code Review: OK`. This
message informs you that the Gerrit service is now running.
The last message confirms that the Gerrit service is running:
`Starting Gerrit Code Review: OK`.
== Update the listen URL
Another recommended task is to change the URL that Gerrit listens to from `*`
to `localhost`. This change helps prevent outside connections from contacting
the instance.
To prevent outside connections from contacting your new Gerrit instance
(strongly recommended), change the URL on which Gerrit listens from `*` to
`localhost`. For example:
....
git config --file ~/gerrit_testsite/etc/gerrit.config httpd.listenUrl 'http://localhost:8080'
@ -83,7 +83,7 @@ git config --file ~/gerrit_testsite/etc/gerrit.config httpd.listenUrl 'http://lo
== Restart the Gerrit service
You must restart the Gerrit service for your authentication type and listen URL
changes to take effect.
changes to take effect:
....
~/gerrit_testsite/bin/gerrit.sh restart
@ -91,8 +91,7 @@ changes to take effect.
== Viewing Gerrit
At this point, you have a basic installation of Gerrit. You can view this
installation by opening a browser and entering the following URL:
To view your new basic installation of Gerrit, go to:
....
http://localhost:8080
@ -100,10 +99,10 @@ http://localhost:8080
== Next steps
Through this quickstart, you now have a simple version of Gerrit running on your
Linux machine. You can use this installation to explore the UI and become
familiar with some of Gerrit's features. For a more detailed installation guide,
see link:install.html[Standalone Daemon Installation Guide].
Now that you have a simple version of Gerrit running, use the installation to
explore the user interface and learn about Gerrit. For more detailed
installation instructions, see
link:[Standalone Daemon Installation Guide](install.html).
GERRIT
------