blob: d36a24d40a738e8ebc7467a2a58176e4596600d8 [file] [log] [blame] [view]
David Pursehoused45b0f82016-08-25 09:37:29 +09001# Developer Guide
2
3[TOC]
4
5## Building
6
David Ostrovskybf2c3912016-11-21 01:37:28 +01007Gitiles requires [Bazel](https://bazel.build/) to build.
8
Ian McKellar1bda1c22017-07-24 15:23:40 -07009You need to use Java for building Gitiles. You can install Bazel from
Fabien Sanglard8cc50222022-09-01 11:09:41 -070010bazel.build: https://bazel.build/versions/master/docs/install.html .
11Alternatively, you can use `apt-get`.
David Pursehoused45b0f82016-08-25 09:37:29 +090012
13```
Fabien Sanglard8cc50222022-09-01 11:09:41 -070014$ sudo apt-get update
15$ sudo apt-get install bazel
David Pursehoused45b0f82016-08-25 09:37:29 +090016```
17
Fabien Sanglard8cc50222022-09-01 11:09:41 -070018The best way to build and run gitiles is to use bazelisk.
19
20```
21$ go install github.com/bazelbuild/bazelisk@latest
22$ export PATH=$PATH:$(go env GOPATH)/bin
23```
Antoine Musso890cc122022-05-21 10:27:58 +020024
25Make sure to initialize and update the git submodules:
26```
27git submodule update --init
28```
29
Fabien Sanglard8cc50222022-09-01 11:09:41 -070030You are now ready to build and test.
31
32```
33$ bazelisk build //:gitiles
34$ bazelisk test //...
35```
36
37## Troubleshooting
38
39If you encounter build errors such as:
40
41```
42Error in execute: Argument 0 of execute is neither a path, label, nor string.
43```
44
Antoine Mussodaac5902022-09-08 15:56:06 +020045Make sure you have `python` available in your PATH. Since Debian 11 and Ubuntu
4620.04 LTS (focal), there is no `/usr/bin/python` provided by default. You can
47install a package to provide a link to Python 3:
Fabien Sanglard8cc50222022-09-01 11:09:41 -070048
49```
Antoine Mussodaac5902022-09-08 15:56:06 +020050sudo apt-get install python-is-python3
Fabien Sanglard8cc50222022-09-01 11:09:41 -070051```
52
53Upon uploading your new CL, if you encounter a message related to a
54missing `Change-Id`, you are missing the commit hook. Likely the command
55to download it should appear in the Hint section of the message. If it
56does not, use the following command:
57
58```
59f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
60```
David Pursehoused45b0f82016-08-25 09:37:29 +090061
ev1stensberg966c93a2018-09-26 10:56:49 +020062## Running Locally and Testing
David Pursehoused45b0f82016-08-25 09:37:29 +090063
64```
65cd /path/to/repositories # Don't run from the gitiles repo.
66/path/to/gitiles/tools/run_dev.sh
67```
68
69This will recompile and start a development server. Open
70http://localhost:8080/ to view your local copy of gitiles, which
71will serve any repositories under `/path/to/repositories`.
72
Réda Housni Alaoui85165062023-09-26 16:04:43 +020073Passing `--debug` option to `tools/run_dev.sh` will suspend the runtime until a
74remote debugger connects to port 5005. If you don't want to suspend the
75runtime, make sure to assign value `n` to environment variable
76`DEFAULT_JVM_DEBUG_SUSPEND`:
77
78```
79cd /path/to/repositories # Don't run from the gitiles repo.
80export DEFAULT_JVM_DEBUG_SUSPEND=n; /path/to/gitiles/tools/run_dev.sh --debug
81```
82
Marco Miller54dad4e2020-01-06 18:15:22 -050083To run unit tests, refer to the aforementioned bazel test command.
David Pursehoused45b0f82016-08-25 09:37:29 +090084
Fabien Sanglard8cc50222022-09-01 11:09:41 -070085## Pushing your changes
86This repository does not work with `repo` tool. To push your CL to
87staging, use the following command.
88
89```
90git push origin HEAD:refs/for/master
91```
92
David Pursehoused45b0f82016-08-25 09:37:29 +090093
94## Eclipse IDE
95
96If you'd like to use Eclipse to edit Gitiles, first generate a project file:
97
98```
David Ostrovskybf2c3912016-11-21 01:37:28 +010099tools/eclipse/project.sh
David Pursehoused45b0f82016-08-25 09:37:29 +0900100```
101
102Import the project in Eclipse:
103
104```
105File -> Import -> Existing Projects into Workpace
106```
107
108The project only needs to be rebuilt if the source roots or third-party
109libraries have changed. For best results, ensure the project is closed in
110Eclipse before rebuilding.
111
Saša Živkov83d066f2016-10-05 16:00:32 +0200112## Running/Debugging from Eclipse IDE
113
114Running Gitiles from Eclipse requires setting the
115`com.google.gitiles.sourcePath` system property. The property value has to be
116the root folder of the Gitiles source code, for example:
117
118````
119-Dcom.google.gitiles.sourcePath=/home/johndoe/git/gitiles
120````
David Pursehoused45b0f82016-08-25 09:37:29 +0900121
122## Code Style
123
124Java code in Gitiles follows the [Google Java Style Guide][java-style]
125with a 100-column limit.
126
127Code should be automatically formatted using [google-java-format][fmt]
128prior to sending a code review. There is currently no Eclipse
129formatter, but the tool can be run from the command line:
130
131```
David Pursehousef35521a2018-09-27 17:05:08 +0900132java -jar /path/to/google-java-format.jar -i path/to/java/File.java
David Pursehoused45b0f82016-08-25 09:37:29 +0900133```
134
135CSS in Gitiles follows the [SUIT CSS naming conventions][suit].
136
137[java-style]: https://google.github.io/styleguide/javaguide.html
138[fmt]: https://github.com/google/google-java-format
139[suit]: https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md
140
141## Code Review
142
143Gitiles uses Gerrit for code review:
144https://gerrit-review.googlesource.com/
145
146Gitiles uses the ["git push" workflow][1] with server
147https://gerrit.googlesource.com/gitiles. You will need a
148[generated cookie][2].
149
150[1]: https://gerrit-review.googlesource.com/Documentation/user-upload.html#_git_push
151[2]: https://gerrit.googlesource.com/new-password
152
153Gerrit depends on "Change-Id" annotations in your commit message.
154If you try to push a commit without one, it will explain how to
155install the proper git-hook:
156
157```
158curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \
159 https://gerrit-review.googlesource.com/tools/hooks/commit-msg
160chmod +x `git rev-parse --git-dir`/hooks/commit-msg
161```
162
163Before you create your local commit (which you'll push to Gerrit)
164you will need to set your email to match your Gerrit account:
165
166```
167git config --local --add user.email foo@bar.com
168```
169
170Normally you will create code reviews by pushing for master:
171
172```
173git push origin HEAD:refs/for/master
174```
Dave Borowitz004c6c02017-08-28 14:36:28 -0400175
176## Releases
177
178Gitiles artifacts are published to the [gerrit-maven
179bucket](http://gerrit-maven.storage.googleapis.com/). To release a new version,
Nasser Grainawibe3c4602021-08-17 09:16:52 -0600180you must have write access to this bucket. See
181[Deploy Gerrit
182Artifacts](https://gerrit-review.googlesource.com/Documentation/dev-release-deploy-config.html)
183for PGP key setup and Google Cloud Storage access setup.
Dave Borowitz004c6c02017-08-28 14:36:28 -0400184
Sven Selbergbc3830e2022-02-10 09:13:06 +0100185First, increment `GITILES_VERSION` in `version.bzl`, Gitiles uses
186[Semantic Versioning](https://semver.org).
187Get your change reviewed and submitted.
Dave Borowitz004c6c02017-08-28 14:36:28 -0400188
189Then, run:
190
191```
192./tools/maven/mvn.sh deploy
193```
194
Nasser Grainawibe3c4602021-08-17 09:16:52 -0600195Tag the release with a signed, annotated tag matching the version number, for
Sven Selbergad155ad2023-01-20 13:24:58 +0000196example "v1.1.0".
David Pursehousee34a28c2017-08-29 08:47:11 +0900197
Dave Borowitz004c6c02017-08-28 14:36:28 -0400198Once released, Maven projects can consume the new version as long as they point
199at the proper repository URL. Similarly, Bazel projects using the `maven_jar`
200bazlet can use the new version with `repository = GERRIT`.