doc: Update DEVELOPMENT.md for local development.

DEVELOPMENT.md

@@ -4,13 +4,19 @@
 
 1. Clone this repo.
 
-2. Copy the Git pre-commit hooks. This will automatically check the build, run
-   tests, and perform linting before each commit. (Symlinks don't seem to work,
-   but if you find a way, please add it here!)
+2.  (OPTIONAL) Copy the Git pre-commit hooks. This will automatically check the build, run
+    tests, and perform linting before each commit. (Symlinks don't seem to work,
+    but if you find a way, please add it here!)
 
-   ```sh
-   cp .githooks/pre-commit .git/hooks/pre-commit
-   ```
+    ```sh
+    cp .githooks/pre-commit .git/hooks/pre-commit
+    ```
+
+    ### Note: You may see this error with the pre-commits due to the monorepo migration:
+    ```
+    [ERROR] No plugin found for prefix 'fmt' in the current project and in the plugin groups [org.apache.maven.plugins, org.codehaus.mojo] available from the repositories [local (/home/alicejli/.m2/repository), central (https://repo.maven.apache.org/maven2)] -> [Help 1]
+    ```
+    Remove the pre-commit hooks. Tracking the issue in https://github.com/googleapis/gapic-generator-java/issues/1253
 
 ## Code Formatting
 
@@ -41,7 +47,7 @@
     mvn test
     ```
 
--   Run a single or multiple unit tests:
+- Run a single or multiple unit tests:
 
     ```sh
     mvn test -Dtest=JavaCodeGeneratorTest
@@ -51,30 +57,30 @@
 
 - Update all unit test golden files:
 
-  ```sh
-  mvn test -DupdateUnitGoldens
-  ```
+    ```sh
+    mvn test -DupdateUnitGoldens
+    ```
 
 - Update a single unit test golden file, for example `JavaCodeGeneratorTest.java`:
 
-  ```sh
-  mvn test -DupdateUnitGoldens -Dtest=JavaCodeGeneratorTest
-  ```
+    ```sh
+    mvn test -DupdateUnitGoldens -Dtest=JavaCodeGeneratorTest
+    ```
 
 - Run a single integration test for API like `Redis`, it generates Java source
   code using the Java microgenerator and compares them with the goldens files
   in `test/integration/goldens/redis`.
 
-  ```sh
-  bazel test //test/integration:redis
-  ```
+    ```sh
+    bazel test //test/integration:redis
+    ```
 
 - Update integration test golden files, for example `Redis`. This clobbers all the
   files in `test/integration/goldens/redis`.
 
-  ```sh
-  bazel run //test/integration:update_redis
-  ```
+    ```sh
+    bazel run //test/integration:update_redis
+    ```
 
 ## Showcase Integration Testing
 
@@ -160,39 +166,64 @@ $ cd showcase
 $ mvn compile -P update
 ```
 
-## Running the Plugin
+## Running the Plugin under googleapis with local gapic-generator-java
 
 See also above section "Showcase Integration Testing".
 
 To generate a production GAPIC API:
 
 1. Clone [googleapis](https://github.com/googleapis/googleapis).
 
-2. Point to local gapic-generator-java
+2. Modify `googleapis/WORKSPACE` to point to local gapic-generator-java
 
    Normally, googleapis's build pulls in googleapis/gapic-generator-java from the
-   Internet:
+   Internet, we need to build a local SNAPSHOT jar first and point googleapis to the SNAPSHOT jar and local copy of the
+   repo.
 
+   Before:
    ```
-   # Java microgenerator.
-   …
-   _gapic_generator_java_version = "2.1.0"
-
-   http_archive(
-       name = "gapic_generator_java",
-       …
-       urls = ["https://github.com/googleapis/gapic-generator-java/archive/v%s.zip" % _gapic_generator_java_version],
-   )
+   _gapic_generator_java_version = "2.13.0"
+
+    maven_install(
+        artifacts = [
+            "com.google.api:gapic-generator-java:" + _gapic_generator_java_version,
+        ],
+        #Update this False for local development
+        fail_on_missing_checksum = True,
+        repositories = [
+            "m2Local",
+            "https://repo.maven.apache.org/maven2/",
+        ]
+    )
+
+    http_archive(
+        name = "gapic_generator_java",
+        strip_prefix = "gapic-generator-java-%s" % _gapic_generator_java_version,
+        urls = ["https://github.com/googleapis/gapic-generator-java/archive/v%s.zip" % _gapic_generator_java_version],
+    )
    ```
 
-   By replacing this portion using the built-in local_repository rule, you can make
-   it refer to your local development repo:
+   After
 
    ```
-   local_repository(
-     name = "gapic_generator_java",
-     path = "/home/<your id>/gapic-generator-java",
-   )
+   _gapic_generator_java_version = "2.13.1-SNAPSHOT"
+
+   maven_install(
+        artifacts = [
+            "com.google.api:gapic-generator-java:" + _gapic_generator_java_version,
+        ],
+        #Update this False for local development
+        fail_on_missing_checksum = False,
+        repositories = [
+            "m2Local",
+            "https://repo.maven.apache.org/maven2/",
+        ]
+    )
+
+    local_repository(
+        name = "gapic_generator_java",
+        path = "/absolute/path/to/your/local/gapic-generator-java",
+    )
    ```
 
 3. Build the new target.
@@ -207,5 +238,26 @@ To generate a production GAPIC API:
    bazel build //google/cloud/speech/v2:google-cloud-speech-v2-java
    ```
 
+   Note: If you are running into bazel build issues, you can try to remove gapic-generator-java cached in your local m2
+   Try running this command:
+   ```
+    rm -rf ~/.m2/repository/com/google/api/
+   ```
+   and then rebuild gapic-generator-java (`mvn clean install`).
+
+## FAQ
+
+### Error in workspace: workspace() got unexpected keyword argument 'managed_directories'
+
+Full Error:
 
+```
+ERROR: Traceback (most recent call last):
+        File "/home/alicejli/googleapis/WORKSPACE", line 1, column 10, in <toplevel>
+                workspace(
+Error in workspace: workspace() got unexpected keyword argument 'managed_directories'
+ERROR: Error computing the main repository mapping: Encountered error while reading extension file 'tools/build_defs/repo/http.bzl': no such package '@bazel_tools//tools/build_defs/repo': error loading package 'external': Could not load //external package
+```
 
+You may be using the latest version of bazel which this project does not support yet. Try installing bazelisk to force
+bazel to use the version specified in `.bazeliskrc`