docs: modify hermetic build docs #3331

JoeWang1127 · 2024-10-31T19:47:12Z

In this PR:

Add instructions on release note generation.
Move generating libraries using docker image to README.md
Move generating libraries using python scripts to DEVELOPMENT.md.
Move instructions on building image to DEVELOPMENT.md.

JoeWang1127 · 2024-10-31T20:08:08Z

hermetic_build/README.md

+
+Instead of running docker image, if you prefer running the underlying python
+script directly, please refer to [development guide](DEVELOPMENT.md) for
+additional instructions.


I think the purpose of README is to instruct users how to do things in the most convenient way, thus I moved the part of running the script directly to development guide as it requires additional setups that users typically don't bother to do.

Instead, I moved the image building part here because it's the most straightforward way (i.e., no need to install dependencies) of generating a repository.

I think the differences between README and DEVELOPMENT is that, README is for external users that just want to run our hermetic image as a product, while DEVELOPMENT is for internal developers that try to maintain the scripts and images.
Hence for README users, they can think hermetic code generation as a blackbox, all they need to know is the input and output. For DEVELOPMENT users, they need to understand how the process uses Python/Shell/Docker etc, so build image locally is better suited for DEVELOPMENT.

SG, I moved the instructions on building image from source to development guide.

diegomarquezp

LGTM overall. Sorry for so many nits!

hermetic_build/README.md

hermetic_build/DEVELOPMENT.md

hermetic_build/README.md

blakeli0 · 2024-11-04T20:33:14Z

hermetic_build/README.md

+   ```shell
+   # Assume you want to generate the library in the current working directory
+   # and the generation configuration is in the same directory.
+   docker run \


This command includes all the possible parameters, can we provide an example with minimum parameters?

Your original example still makes sense for more advanced use cases, I didn't mean to ask you to delete it, we can still have another example with all the parameters. On the other hand, maybe we don't have to provide a more complex example as it could confuse other users. So either way works for me, feel free to decide as you see fit.

I added back the advance example with explanations.

hermetic_build/DEVELOPMENT.md

diegomarquezp · 2024-11-04T21:36:12Z

hermetic_build/README.md

@@ -129,7 +137,7 @@ They are shared by all GAPICs of a library.
 | distribution_name     |    No    | `{group_id}:google-{cloud_prefix}{library_name}` if not specified                                                                         |
 | excluded_poms         |    No    |                                                                                                                                           |
 | excluded_dependencies |    No    |                                                                                                                                           |
-| googleapis_commitish  |    No    | use repository level `googleapis_commitish` if not specified.                                                                             |
+| googleapis_commitish  |    No    | use repository level `googleapis_committish` if not specified.                                                                            |


Yes, it should be googleapis_committish according to #3208 (comment).

However, I think the refactor should be in its own PR.

Sorry I misspelled the suggestion string. I was trying to point out that we should stick to googleapis_commitish (one t) since we haven't done such refactor.

hermetic_build/README.md

hermetic_build/release_note_generation/cli/generate_release_note.py

blakeli0 · 2024-11-04T21:54:02Z

hermetic_build/README.md

+     -u "$(id -u):$(id -g)" \
+     -v "$(pwd):/workspace" \
+     -v /path/to/api_definition:/workspace \
+     -e GENERATOR_VERSION=image-tag \


Do we have to set GENERATOR_VERSION? Is it still used in our scritps? Can we just inline the image-tag?

OK, I can see generator version is defined in the generation config example.

I'll remove this param.

sonarcloud · 2024-11-05T15:55:15Z

Quality Gate passed for 'gapic-generator-java-root'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

sonarcloud · 2024-11-05T15:58:23Z

Quality Gate passed for 'java_showcase_integration_tests'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

🤖 I have created a release *beep* *boop* --- <details><summary>2.50.0</summary> ## [2.50.0](v2.49.0...v2.50.0) (2024-11-14) ### Features * Add experimental S2A integration in client libraries grpc transport ([#3326](#3326)) ([1138ca6](1138ca6)) * enable selective generation based on service config include list ([#3323](#3323)) ([0cddadb](0cddadb)) * introduce `java.time` to java-core ([#3330](#3330)) ([f202c3b](f202c3b)) * Update Gapic-Generator to generate libraries using `java.time` methods ([#3321](#3321)) ([b21c9a4](b21c9a4)) ### Bug Fixes * Fix flaky test ScheduledRetryingExecutorTest.testCancelOuterFutureAfterStart ([#3335](#3335)) ([e73740d](e73740d)) * httpjson callables to trace attempts (started, failed) ([#3300](#3300)) ([15a64ee](15a64ee)) * instantiate GaxProperties at build time to ensure we get the protobuf version ([#3365](#3365)) ([bb2a3be](bb2a3be)) * protobuf version not always getting set in headers ([#3322](#3322)) ([7f6e470](7f6e470)) * use BuildKit instead of legacy builder to build the Hermetic Build images ([#3338](#3338)) ([222fb45](222fb45)) ### Dependencies * update google auth library dependencies to v1.30.0 ([#3367](#3367)) ([a31c682](a31c682)) * update grpc dependencies to v1.68.1 ([#3240](#3240)) ([c8e3941](c8e3941)) ### Documentation * fix list num ([#3356](#3356)) ([b7d6296](b7d6296)) * **hermetic-build:** indicate usage of Docker Buildkit in development guide ([#3337](#3337)) ([01e742d](01e742d)) * modify hermetic build docs ([#3331](#3331)) ([25023af](25023af)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

JoeWang1127 added 2 commits October 31, 2024 12:20

docs: modify hermetic build docs

b5109a7

change comments in cli

52386c7

product-auto-label bot added the size: m Pull request size is medium. label Oct 31, 2024

JoeWang1127 added 2 commits October 31, 2024 16:00

add instructions on how to generate release note

0a3641a

restore param

425ba11

JoeWang1127 commented Oct 31, 2024

View reviewed changes

add notes in docker run

55c2b40

product-auto-label bot added size: l Pull request size is large. and removed size: m Pull request size is medium. labels Nov 1, 2024

JoeWang1127 marked this pull request as ready for review November 1, 2024 16:08

JoeWang1127 requested review from blakeli0 and diegomarquezp November 1, 2024 16:08

diegomarquezp reviewed Nov 1, 2024

View reviewed changes

JoeWang1127 added 2 commits November 4, 2024 09:43

rephase

7524b65

rephase

64dc16b

diegomarquezp approved these changes Nov 4, 2024

View reviewed changes

JoeWang1127 added 3 commits November 4, 2024 10:29

move build image steps to development guide

19ebfb2

change title

acf40ff

change shell type

eba3cb7

JoeWang1127 requested a review from diegomarquezp November 4, 2024 15:32

Merge branch 'main' into docs/modify-hermetic-build-docs

44b4baf

blakeli0 reviewed Nov 4, 2024

View reviewed changes

hermetic_build/README.md Outdated Show resolved Hide resolved

blakeli0 reviewed Nov 4, 2024

View reviewed changes

simplify docker run

dee681d

JoeWang1127 requested a review from blakeli0 November 4, 2024 21:23

diegomarquezp approved these changes Nov 4, 2024

View reviewed changes

rephase

a68ef4d

blakeli0 reviewed Nov 4, 2024

View reviewed changes

remove generator env in docker run

244f82a

JoeWang1127 requested a review from blakeli0 November 4, 2024 22:03

JoeWang1127 added 3 commits November 5, 2024 08:06

add an advanced example of docker run

d31dc36

add a note

a7b585f

restore

df96948

blakeli0 approved these changes Nov 5, 2024

View reviewed changes

JoeWang1127 merged commit 25023af into main Nov 5, 2024
49 checks passed

JoeWang1127 deleted the docs/modify-hermetic-build-docs branch November 5, 2024 16:44

release-please bot mentioned this pull request Nov 4, 2024

chore(main): release 2.50.0 #3327

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: modify hermetic build docs #3331

docs: modify hermetic build docs #3331

JoeWang1127 commented Oct 31, 2024 •

edited

Loading

JoeWang1127 Oct 31, 2024

blakeli0 Nov 1, 2024

JoeWang1127 Nov 4, 2024

diegomarquezp left a comment

blakeli0 Nov 4, 2024

JoeWang1127 Nov 4, 2024

blakeli0 Nov 4, 2024

JoeWang1127 Nov 5, 2024

diegomarquezp Nov 4, 2024 •

edited

Loading

JoeWang1127 Nov 4, 2024

diegomarquezp Nov 4, 2024

blakeli0 Nov 4, 2024

JoeWang1127 Nov 4, 2024

sonarcloud bot commented Nov 5, 2024

sonarcloud bot commented Nov 5, 2024

	\| googleapis_commitish \| No \| use repository level `googleapis_committish` if not specified. \|
	\| googleapis_commitish \| No \| use repository level `googleapis_commitish` if not specified. \|

docs: modify hermetic build docs #3331

docs: modify hermetic build docs #3331

Conversation

JoeWang1127 commented Oct 31, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

diegomarquezp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

diegomarquezp Nov 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sonarcloud bot commented Nov 5, 2024

Quality Gate passed for 'gapic-generator-java-root'

sonarcloud bot commented Nov 5, 2024

Quality Gate passed for 'java_showcase_integration_tests'

JoeWang1127 commented Oct 31, 2024 •

edited

Loading

diegomarquezp Nov 4, 2024 •

edited

Loading