chore(docs): document how code is generated (#18880)

* chore(docs): document how code is generated

Credit: Diego's https://docs.google.com/document/d/1fcg-Gg6sq8JSHzo-baHeAeXDkkCRDiabDwjmIke1lwU/edit?usp=sharing

* Update README.md

* Update README.md

* Moved the source code comment to YAML

* comment

* Update README.md

Co-authored-by: Diego Marquez <diegomarquezp@google.com>

---------

Co-authored-by: Diego Marquez <diegomarquezp@google.com>

Author: suztomo

.github/workflows/codegen.yaml

@@ -7,6 +7,7 @@ on:
 name: codegen
 jobs:
   discovery:
+    # As of November 2023, it returns 269 service names.
     uses: googleapis/discovery-artifact-manager/.github/workflows/list-services.yml@master
   total_service_size_check:
     runs-on: ubuntu-20.04
@@ -26,6 +27,9 @@ jobs:
     runs-on: ubuntu-20.04
     needs: discovery
     outputs:
+      # As of November 2023, the output of batch job is a 3-element array, which contains a chunk of 100 service names
+      # at the index 0, a chunk of other 100 service names at the index 1, and a chunk of remaining 69 service names
+      # at the index 2.
       services: ${{ steps.chunk.outputs.result }}
     steps:
       - uses: actions/github-script@v5
@@ -48,7 +52,10 @@ jobs:
     uses: googleapis/google-api-java-client-services/.github/workflows/generate.yaml@main
     needs: batch
     secrets: inherit
-    # The number of batch is implicitly decided by the hour of the day
+    # The size of the batch is implicitly decided by the hour of the day.
+    # For example, a job starting at "1:30" uses the chunk at the index 1 in the array.
+    # If you manually invoke the workflow other hours than 0:00 - 2:59 and the array's length is 3,
+    # this job is skipped because there's no element at the index in the array.
     if: ${{!!fromJson(needs.batch.outputs.services).batches[fromJson(needs.batch.outputs.services).hour]}}
     with: 
       services: ${{toJson(fromJson(needs.batch.outputs.services).batches[fromJson(needs.batch.outputs.services).hour])}}

README.md

@@ -262,7 +262,39 @@ see the [project's README](https://github.com/googleapis/google-auth-library-jav
 for how to use credentials with google-http-client and
 [javadoc](https://cloud.google.com/java/docs/reference/google-auth-library/latest/overview) for more details.
 
-## Generating the API clients
+## How the code is updated and published
+
+When a change is made in the API definitions, the following events happens:
+
+1. [The discovery-artifact-manager repository](https://github.com/googleapis/discovery-artifact-manager) has
+   [update-discoveries job](https://github.com/googleapis/discovery-artifact-manager/blob/master/.github/workflows/update-disco.yml)
+   that copies the definition files from https://discovery.googleapis.com/discovery/v1/apis to
+   the repository.
+2. This google-api-java-client-services repository has ([codegen workflow](
+   https://github.com/googleapis/google-api-java-client-services/blob/main/.github/workflows/codegen.yaml)).
+   This daily workflow has the following jobs:
+    - **discovery**: It uses the discovery-artifact-manager repository's [List discovery services workflow](
+      https://github.com/googleapis/discovery-artifact-manager/blob/master/.github/workflows/list-services.yml)
+      to list the service names.
+      Example values in the returned array include "storage" (from `discoveries/storage.v1.json`) and "admin"
+      (from `discoveries/admin.datatransfer_v1.json`).
+    - **total_service_size_check**: This job ensures the size of the service name array does not exceed 300
+      (00:30 to 02:30 implies 3 batches of size 100); otherwise it fails.
+      As of November 2023, the size of the service name array is 269.
+    - **batch** This job splits the service names into chunks of maximum 100 and returns an array containing the chunks.
+      This is to avoid one job that is too long to finish and also to avoid hitting the maximum parallel job limit of Github actions (256).
+    - **generate**: At the end, this job runs the code generator for each service in the chunk whose array index
+      corresponds to the hour of the day. For details, see [codegen.yaml](
+      https://github.com/googleapis/google-api-java-client-services/blob/main/.github/workflows/codegen.yaml).
+      If there are code changes, this job creates pull requests
+      (Example: [#18860](https://github.com/googleapis/google-api-java-client-services/pull/18860)).
+3. The yoshi-approver and merge-on-green bots merge the pull requests automatically.
+4. [The Kokoro job](http://fusion2/search?q=google-api-java-client-services%2Frelease&s=p)
+   publishes the libraries in this repository.
+
+## Generating the API clients locally
+
+If you want to generate certain code locally for troubleshooting purpose, please follow these steps:
 
 Generating the API clients requires git and Python 3.6.