David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 1 | # Developer Guide |
| 2 | |
| 3 | [TOC] |
| 4 | |
| 5 | ## Building |
| 6 | |
David Ostrovsky | bf2c391 | 2016-11-21 01:37:28 +0100 | [diff] [blame] | 7 | Gitiles requires [Bazel](https://bazel.build/) to build. |
| 8 | |
Ian McKellar | 1bda1c2 | 2017-07-24 15:23:40 -0700 | [diff] [blame] | 9 | You need to use Java for building Gitiles. You can install Bazel from |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 10 | bazel.build: https://bazel.build/versions/master/docs/install.html . |
| 11 | Alternatively, you can use `apt-get`. |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 12 | |
| 13 | ``` |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 14 | $ sudo apt-get update |
| 15 | $ sudo apt-get install bazel |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 16 | ``` |
| 17 | |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 18 | The 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 Musso | 890cc12 | 2022-05-21 10:27:58 +0200 | [diff] [blame] | 24 | |
| 25 | Make sure to initialize and update the git submodules: |
| 26 | ``` |
| 27 | git submodule update --init |
| 28 | ``` |
| 29 | |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 30 | You are now ready to build and test. |
| 31 | |
| 32 | ``` |
| 33 | $ bazelisk build //:gitiles |
| 34 | $ bazelisk test //... |
| 35 | ``` |
| 36 | |
| 37 | ## Troubleshooting |
| 38 | |
| 39 | If you encounter build errors such as: |
| 40 | |
| 41 | ``` |
| 42 | Error in execute: Argument 0 of execute is neither a path, label, nor string. |
| 43 | ``` |
| 44 | |
Antoine Musso | daac590 | 2022-09-08 15:56:06 +0200 | [diff] [blame] | 45 | Make sure you have `python` available in your PATH. Since Debian 11 and Ubuntu |
| 46 | 20.04 LTS (focal), there is no `/usr/bin/python` provided by default. You can |
| 47 | install a package to provide a link to Python 3: |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 48 | |
| 49 | ``` |
Antoine Musso | daac590 | 2022-09-08 15:56:06 +0200 | [diff] [blame] | 50 | sudo apt-get install python-is-python3 |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 51 | ``` |
| 52 | |
| 53 | Upon uploading your new CL, if you encounter a message related to a |
| 54 | missing `Change-Id`, you are missing the commit hook. Likely the command |
| 55 | to download it should appear in the Hint section of the message. If it |
| 56 | does not, use the following command: |
| 57 | |
| 58 | ``` |
| 59 | f=`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 Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 61 | |
ev1stensberg | 966c93a | 2018-09-26 10:56:49 +0200 | [diff] [blame] | 62 | ## Running Locally and Testing |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 63 | |
| 64 | ``` |
| 65 | cd /path/to/repositories # Don't run from the gitiles repo. |
| 66 | /path/to/gitiles/tools/run_dev.sh |
| 67 | ``` |
| 68 | |
| 69 | This will recompile and start a development server. Open |
| 70 | http://localhost:8080/ to view your local copy of gitiles, which |
| 71 | will serve any repositories under `/path/to/repositories`. |
| 72 | |
Réda Housni Alaoui | 8516506 | 2023-09-26 16:04:43 +0200 | [diff] [blame] | 73 | Passing `--debug` option to `tools/run_dev.sh` will suspend the runtime until a |
| 74 | remote debugger connects to port 5005. If you don't want to suspend the |
| 75 | runtime, make sure to assign value `n` to environment variable |
| 76 | `DEFAULT_JVM_DEBUG_SUSPEND`: |
| 77 | |
| 78 | ``` |
| 79 | cd /path/to/repositories # Don't run from the gitiles repo. |
| 80 | export DEFAULT_JVM_DEBUG_SUSPEND=n; /path/to/gitiles/tools/run_dev.sh --debug |
| 81 | ``` |
| 82 | |
Marco Miller | 54dad4e | 2020-01-06 18:15:22 -0500 | [diff] [blame] | 83 | To run unit tests, refer to the aforementioned bazel test command. |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 84 | |
Fabien Sanglard | 8cc5022 | 2022-09-01 11:09:41 -0700 | [diff] [blame] | 85 | ## Pushing your changes |
| 86 | This repository does not work with `repo` tool. To push your CL to |
| 87 | staging, use the following command. |
| 88 | |
| 89 | ``` |
| 90 | git push origin HEAD:refs/for/master |
| 91 | ``` |
| 92 | |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 93 | |
| 94 | ## Eclipse IDE |
| 95 | |
| 96 | If you'd like to use Eclipse to edit Gitiles, first generate a project file: |
| 97 | |
| 98 | ``` |
David Ostrovsky | bf2c391 | 2016-11-21 01:37:28 +0100 | [diff] [blame] | 99 | tools/eclipse/project.sh |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 100 | ``` |
| 101 | |
| 102 | Import the project in Eclipse: |
| 103 | |
| 104 | ``` |
| 105 | File -> Import -> Existing Projects into Workpace |
| 106 | ``` |
| 107 | |
| 108 | The project only needs to be rebuilt if the source roots or third-party |
| 109 | libraries have changed. For best results, ensure the project is closed in |
| 110 | Eclipse before rebuilding. |
| 111 | |
Saša Živkov | 83d066f | 2016-10-05 16:00:32 +0200 | [diff] [blame] | 112 | ## Running/Debugging from Eclipse IDE |
| 113 | |
| 114 | Running Gitiles from Eclipse requires setting the |
| 115 | `com.google.gitiles.sourcePath` system property. The property value has to be |
| 116 | the root folder of the Gitiles source code, for example: |
| 117 | |
| 118 | ```` |
| 119 | -Dcom.google.gitiles.sourcePath=/home/johndoe/git/gitiles |
| 120 | ```` |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 121 | |
| 122 | ## Code Style |
| 123 | |
| 124 | Java code in Gitiles follows the [Google Java Style Guide][java-style] |
| 125 | with a 100-column limit. |
| 126 | |
| 127 | Code should be automatically formatted using [google-java-format][fmt] |
| 128 | prior to sending a code review. There is currently no Eclipse |
| 129 | formatter, but the tool can be run from the command line: |
| 130 | |
| 131 | ``` |
David Pursehouse | f35521a | 2018-09-27 17:05:08 +0900 | [diff] [blame] | 132 | java -jar /path/to/google-java-format.jar -i path/to/java/File.java |
David Pursehouse | d45b0f8 | 2016-08-25 09:37:29 +0900 | [diff] [blame] | 133 | ``` |
| 134 | |
| 135 | CSS 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 | |
| 143 | Gitiles uses Gerrit for code review: |
| 144 | https://gerrit-review.googlesource.com/ |
| 145 | |
| 146 | Gitiles uses the ["git push" workflow][1] with server |
| 147 | https://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 | |
| 153 | Gerrit depends on "Change-Id" annotations in your commit message. |
| 154 | If you try to push a commit without one, it will explain how to |
| 155 | install the proper git-hook: |
| 156 | |
| 157 | ``` |
| 158 | curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ |
| 159 | https://gerrit-review.googlesource.com/tools/hooks/commit-msg |
| 160 | chmod +x `git rev-parse --git-dir`/hooks/commit-msg |
| 161 | ``` |
| 162 | |
| 163 | Before you create your local commit (which you'll push to Gerrit) |
| 164 | you will need to set your email to match your Gerrit account: |
| 165 | |
| 166 | ``` |
| 167 | git config --local --add user.email foo@bar.com |
| 168 | ``` |
| 169 | |
| 170 | Normally you will create code reviews by pushing for master: |
| 171 | |
| 172 | ``` |
| 173 | git push origin HEAD:refs/for/master |
| 174 | ``` |
Dave Borowitz | 004c6c0 | 2017-08-28 14:36:28 -0400 | [diff] [blame] | 175 | |
| 176 | ## Releases |
| 177 | |
| 178 | Gitiles artifacts are published to the [gerrit-maven |
| 179 | bucket](http://gerrit-maven.storage.googleapis.com/). To release a new version, |
Nasser Grainawi | be3c460 | 2021-08-17 09:16:52 -0600 | [diff] [blame] | 180 | you must have write access to this bucket. See |
| 181 | [Deploy Gerrit |
| 182 | Artifacts](https://gerrit-review.googlesource.com/Documentation/dev-release-deploy-config.html) |
| 183 | for PGP key setup and Google Cloud Storage access setup. |
Dave Borowitz | 004c6c0 | 2017-08-28 14:36:28 -0400 | [diff] [blame] | 184 | |
Sven Selberg | bc3830e | 2022-02-10 09:13:06 +0100 | [diff] [blame] | 185 | First, increment `GITILES_VERSION` in `version.bzl`, Gitiles uses |
| 186 | [Semantic Versioning](https://semver.org). |
| 187 | Get your change reviewed and submitted. |
Dave Borowitz | 004c6c0 | 2017-08-28 14:36:28 -0400 | [diff] [blame] | 188 | |
| 189 | Then, run: |
| 190 | |
| 191 | ``` |
| 192 | ./tools/maven/mvn.sh deploy |
| 193 | ``` |
| 194 | |
Nasser Grainawi | be3c460 | 2021-08-17 09:16:52 -0600 | [diff] [blame] | 195 | Tag the release with a signed, annotated tag matching the version number, for |
Sven Selberg | ad155ad | 2023-01-20 13:24:58 +0000 | [diff] [blame] | 196 | example "v1.1.0". |
David Pursehouse | e34a28c | 2017-08-29 08:47:11 +0900 | [diff] [blame] | 197 | |
Dave Borowitz | 004c6c0 | 2017-08-28 14:36:28 -0400 | [diff] [blame] | 198 | Once released, Maven projects can consume the new version as long as they point |
| 199 | at the proper repository URL. Similarly, Bazel projects using the `maven_jar` |
| 200 | bazlet can use the new version with `repository = GERRIT`. |