Adding a developer documentation entry point

This documentation explains how to set-ups an Eclipse IDE, how to build
and tests Bazel and the first part of the documentation. It also update
the FAQ accordingly.

--
MOS_MIGRATED_REVID=88556053

3 files changed, 104 insertions, 43 deletions

diff --git a/docs/FAQ.md b/docs/FAQ.md
index bb1658b98d..a3d9cca831 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -344,9 +344,8 @@ What future features can we expect in Bazel?
 Our initial goal is to work on Google's internal use-cases. This
 includes Google's principal languages (C++, Java, Go) and major
 platforms (Linux, Android, iOS).  For practical reasons, not all of
-these are currently open-sourced.
-
-TODO(bazel-team): add link to public roadmap.
+these are currently open-sourced. For more details see our
+[roadmap](bazel-roadmap.md).
 
 
 What about Python?
@@ -371,7 +370,7 @@ Can I use Bazel for my LISP/Python/Haskell/Scala/Rust project?
 We have an extension mechanism that allows you to add new rules
 without recompiling Bazel.
 
-For documentation: see TODO(bazel-team).
+For documentation: see [here](skylark-index.md).
 
 At present, the extension mechanism is experimental though.
 
@@ -387,24 +386,8 @@ the mailing list for advice: bazel-discuss@googlegroups.com.
 Can I contribute to the Bazel code base?
 ----------------------------------------
 
-Not yet, but we are working on a process.
-
-Please consider the following:
-
-* Before starting to code, discuss your plan to make sure we agree on
-  it. We can be reached at bazel-discuss@googlegroups.com.
-
-* All contributors must sign a Contributor License Agreement at
-
-   https://cla.developers.google.com/
-
-* All contributions will have to go through pre-commit code review.
-
-* Contributions need a Google team member as sponsor.
-
-TODO(bazel-team): set up a process
-
-TODO(bazel-team): link to detailed patch acceptance policy.
+You can propose patches to Bazel. You can find all the details in the
+[contribution guidelines](contribution.md).
 
 
 Why isn't all development done in the open?
@@ -412,9 +395,8 @@ Why isn't all development done in the open?
 
 We still have to refactor the interfaces between the public code in
 Bazel and our internal extensions frequently. This makes it hard to do
-much development in the open.
-
-TODO(bazel-team): link to roadmap.
+much development in the open. See our [governance plan](governance.md)
+for more details.
 
 
 How do I contact the team?
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000000..9af6bf42c6
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,97 @@
+# Contributing to Bazel
+
+## How can I contribute to Bazel?
+
+You should first read the [Bazel governance plan](governance.md). Then you can
+read this page that explains how to set-up and work on the Bazel code and how
+to submit a patch to Bazel.
+
+## Setting-up your coding environment
+
+For now we only have partial support for the Eclipse IDE for Java. We don't have
+IDE support for others languages in Bazel right now.
+
+### Creating an Eclipse project
+
+To work with Eclipse, run from the root of the source tree `sh
+scripts/setup-eclipse.sh` and it will create the `.project` and the `.classpath`
+files (if a `.project` file is present, only the `.classpath` will get
+overwritten). You can then import the project in Eclipse.
+
+_You might see some errors in Eclipse concerning Truth assertions_
+
+### Compiling Bazel {#compile-bazel}
+
+To test out bazel, you need to compile it. There is currently two ways of
+compiling it:
+
+* `sh compile.sh` build a Bazel binary without Bazel, it should only be used to
+  bootstrap Bazel itself. The resulting binary can be found at `output/bazel`.
+* `bazel build //src:bazel` builds the Bazel binary using Bazel and the
+  resulting binary can be found at `bazel-bin/src/bazel`.
+
+In addition to the Bazel binary, you might want to build the various tools Bazel
+uses:
+
+* For Java support
+  * JavaBuilder is the java compiler wrapper used by Bazel and its target can be
+    found at `//src/java_tools/buildjar:JavaBuilder_deploy.jar`.
+  * SingleJar is a tool to assemble a single jar composed of all classes from
+    all jar dependencies (build the `*_deploy.jar` files), it can be found at
+    `//src/java_tools/singlejar:SingleJar_deploy.jar`.
+  * ijar is a tool to extracts the class interfaces of jars and is a third
+    party software at `//third_party/ijar`.
+* For Objective-C / iOS support
+  * TODO(bazel-team): fill ups the tools description
+
+When modifying Bazel, you want to make sure that the following still works:
+
+* Bootstrap test with `sh bootstrap_test.sh all` after having removed the
+  `output` directory: it rebuilds Bazel with `./compile.sh`, Bazel with the
+  `compile.sh` Bazel and Bazel with the Bazel-built binary. It compares if the
+  constructed Bazel builts are identical and then run all bazel tests with
+  `bazel test //src/...`.
+* ijar's tests with `bazel test //third_party/ijar/test/...`
+* Building testing the examples in the `base_workspace` directory.
+  `bazel test --nobuild_tests_only //...` in that directory should build and test
+  everything (you might need to set-up extra tools following the instructions in
+  the README files for each example).
+
+## Bazel's code description
+
+Bazel is organized in several parts:
+
+* A client code in C++ that talk to the server code in java and provide the
+  command-line interface. Its code is in `src/main/cpp`.
+* Protocol buffers in `src/main/protobuf`.
+* The server code in Java (in `src/main/java` and `src/test/java`)
+  * Core code which is mostly composed of [SkyFrame](skyframe.md) and some
+    utilities.
+  * [Skylark](skylark_index.md) rules are defined in `tools/build_rules`. If you
+    want to add rules, consider using [Skylark](skylark_index.md) first.
+  * Builtin rules in `com.google.devtools.build.lib.rules` and in
+    `com.google.devtools.build.lib.bazel.rules`.
+* Java native interfaces in `src/main/native`.
+* Various tooling for language support (see the list in the
+  [compiling Bazel](#compile-bazel) section.
+
+## Patch Acceptance Process
+
+1. Discuss your plan and design, and get agreement on our [mailing
+   list](https://groups.google.com/forum/#!forum/bazel-discuss).
+2. Prepare a patch that implements the feature. Don't forget to add tests.
+3. Upload to [Gerrit](https://bazel-review.googlesource.com); Gerrit upload
+   requires that you have signed a
+   [Contributor License Agreement](https://cla.developers.google.com/).
+4. Complete a code review with a core contributor.
+5. An engineer at Google applies the patch to our internal version control
+   system.
+6. The patch is exported as a Git commit, at which point the Gerrit code review
+   is closed.
+
+We do not currently accept pull requests on GitHub.
+
+We will make changes to this process as necessary, and we're hoping to move
+closer to a fully open development model in the future (also see
+[Is Bazel developed fully in the open?](governance.md#isbazelopen)).
+
diff --git a/docs/governance.md b/docs/governance.md
index cf65b76a96..21a74efe17 100644
--- a/docs/governance.md
+++ b/docs/governance.md
@@ -61,21 +61,3 @@ The current group is:
  - `lberki`
  - `philwo`
  - `ulfjack`
-
-### Patch Acceptance Process
-
-1. Discuss your plan and design, and get agreement on our [mailing
-   list](https://groups.google.com/forum/#!forum/bazel-discuss).
-2. Prepare a patch that implements the feature. Don't forget to add tests.
-3. Upload to [Gerrit](https://www.to-be-determined.com); Gerrit upload requires that you have signed
-   a [Contributor License Agreement](https://cla.developers.google.com/).
-4. Complete a code review with a core contributor.
-5. An engineer at Google applies the patch to our internal version control system.
-6. The patch is exported as a Git commit, at which point the Gerrit code review is closed.
-
-We do not currently accept pull requests on GitHub.
-
-We will make changes to this process as necessary, and we're hoping to move closer to a fully open
-development model in the future (also see [Is Bazel developed fully in the open?](#isbazelopen)
-above).
-