README: Move development information to a separate file in /Documentation Move the development information to "Developer Guide" under the documentation folder, and link to it from README. Later changes will add another separate document for configuration. Change-Id: Iee66f26ea21c98667faa0ebe5f8e19e6501d9638
diff --git a/Documentation/developer-guide.md b/Documentation/developer-guide.md new file mode 100644 index 0000000..2d4af0f --- /dev/null +++ b/Documentation/developer-guide.md
@@ -0,0 +1,108 @@ +# Developer Guide + +[TOC] + +## Building + +Gitiles requires [Buck](http://facebook.github.io/buck/) to build. + +``` +sudo apt-get install ant +cd ${HOME} +git clone https://github.com/facebook/buck.git +cd buck +ant +sudo ln -s ${PWD}/bin/buck /usr/bin/buck +cd /path/to/gitiles +git submodule update --init +buck build all +buck test +``` + + +## Testing + +``` +cd /path/to/repositories # Don't run from the gitiles repo. +/path/to/gitiles/tools/run_dev.sh +``` + +This will recompile and start a development server. Open +http://localhost:8080/ to view your local copy of gitiles, which +will serve any repositories under `/path/to/repositories`. + +To run unit tests, run `buck test`. + + +## Eclipse IDE + +If you'd like to use Eclipse to edit Gitiles, first generate a project file: + +``` +./bucklets/tools/eclipse.py --src +``` + +Import the project in Eclipse: + +``` +File -> Import -> Existing Projects into Workpace +``` + +The project only needs to be rebuilt if the source roots or third-party +libraries have changed. For best results, ensure the project is closed in +Eclipse before rebuilding. + + +## Code Style + +Java code in Gitiles follows the [Google Java Style Guide][java-style] +with a 100-column limit. + +Code should be automatically formatted using [google-java-format][fmt] +prior to sending a code review. There is currently no Eclipse +formatter, but the tool can be run from the command line: + +``` +java -jar /path/to/google-java-format-1.0-all-deps.jar -i path/to/java/File.java +``` + +CSS in Gitiles follows the [SUIT CSS naming conventions][suit]. + +[java-style]: https://google.github.io/styleguide/javaguide.html +[fmt]: https://github.com/google/google-java-format +[suit]: https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md + +## Code Review + +Gitiles uses Gerrit for code review: +https://gerrit-review.googlesource.com/ + +Gitiles uses the ["git push" workflow][1] with server +https://gerrit.googlesource.com/gitiles. You will need a +[generated cookie][2]. + +[1]: https://gerrit-review.googlesource.com/Documentation/user-upload.html#_git_push +[2]: https://gerrit.googlesource.com/new-password + +Gerrit depends on "Change-Id" annotations in your commit message. +If you try to push a commit without one, it will explain how to +install the proper git-hook: + +``` +curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \ + https://gerrit-review.googlesource.com/tools/hooks/commit-msg +chmod +x `git rev-parse --git-dir`/hooks/commit-msg +``` + +Before you create your local commit (which you'll push to Gerrit) +you will need to set your email to match your Gerrit account: + +``` +git config --local --add user.email [email protected] +``` + +Normally you will create code reviews by pushing for master: + +``` +git push origin HEAD:refs/for/master +```