Repository navigation
docs: modify hermetic build docs - #3331
Conversation
|
|
||
| Instead of running docker image, if you prefer running the underlying python | ||
| script directly, please refer to [development guide](DEVELOPMENT.md) for | ||
| additional instructions. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
SG, I moved the instructions on building image from source to development guide.
| ```shell | ||
| # Assume you want to generate the library in the current working directory | ||
| # and the generation configuration is in the same directory. | ||
| docker run \ |
There was a problem hiding this comment.
This command includes all the possible parameters, can we provide an example with minimum parameters?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I added back the advance example with explanations.
| | 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. | |
There was a problem hiding this comment.
| | googleapis_commitish | No | use repository level `googleapis_committish` if not specified. | | |
| | googleapis_commitish | No | use repository level `googleapis_commitish` if not specified. | |
Not the right spelling but it's what's defined in the repo-level section.
There was a problem hiding this comment.
Yes, it should be googleapis_committish according to #3208 (comment).
However, I think the refactor should be in its own PR.
There was a problem hiding this comment.
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.
| -u "$(id -u):$(id -g)" \ | ||
| -v "$(pwd):/workspace" \ | ||
| -v /path/to/api_definition:/workspace \ | ||
| -e GENERATOR_VERSION=image-tag \ |
There was a problem hiding this comment.
Do we have to set GENERATOR_VERSION? Is it still used in our scritps? Can we just inline the image-tag?
There was a problem hiding this comment.
OK, I can see generator version is defined in the generation config example.
I'll remove this param.
commented
Nov 5, 2024
|
commented
Nov 5, 2024
|



In this PR:
README.mdDEVELOPMENT.md.DEVELOPMENT.md.