Skip to content
This repository was archived by the owner on Oct 29, 2026. It is now read-only.

docs: modify hermetic build docs - #3331

Merged
JoeWang1127 merged 17 commits into
mainfrom
docs/modify-hermetic-build-docs
Nov 5, 2024
Merged

JoeWang1127 merged 17 commits into
mainfrom
docs/modify-hermetic-build-docs

Conversation

@JoeWang1127

@JoeWang1127 JoeWang1127 commented Oct 31, 2024 •

Copy link
Copy Markdown
Contributor

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.

@product-auto-label product-auto-label Bot added the size: m Pull request size is medium. label Oct 31, 2024
Comment thread hermetic_build/README.md Outdated

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@product-auto-label 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
JoeWang1127 marked this pull request as ready for review November 1, 2024 16:08

ghost left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM overall. Sorry for so many nits!

Comment thread hermetic_build/README.md Resolved
Comment thread hermetic_build/README.md Resolved
Comment thread hermetic_build/README.md Resolved
Comment thread hermetic_build/README.md Resolved
Comment thread hermetic_build/README.md Resolved
Comment thread hermetic_build/DEVELOPMENT.md Resolved
Comment thread hermetic_build/DEVELOPMENT.md Resolved
Comment thread hermetic_build/DEVELOPMENT.md Resolved
Comment thread hermetic_build/DEVELOPMENT.md Resolved
Comment thread hermetic_build/DEVELOPMENT.md Resolved
Comment thread hermetic_build/README.md Resolved
Comment thread 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 \

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

ghost Nov 5, 2024

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added back the advance example with explanations.

@JoeWang1127
JoeWang1127 requested a review from blakeli0 November 4, 2024 21:23
Comment thread hermetic_build/DEVELOPMENT.md Resolved
Comment thread hermetic_build/README.md Outdated
| 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. |

ghost Nov 4, 2024 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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.

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread hermetic_build/README.md Resolved
Comment thread hermetic_build/README.md Outdated
-u "$(id -u):$(id -g)" \
-v "$(pwd):/workspace" \
-v /path/to/api_definition:/workspace \
-e GENERATOR_VERSION=image-tag \

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ghost Nov 4, 2024

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

I'll remove this param.

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

ghost commented Nov 5, 2024

Copy link
Copy Markdown

@sonarqubecloud

ghost commented Nov 5, 2024

Copy link
Copy Markdown

Quality Gate Passed 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

@JoeWang1127
JoeWang1127 merged commit 25023af into main Nov 5, 2024
@JoeWang1127
JoeWang1127 deleted the docs/modify-hermetic-build-docs branch November 5, 2024 16:44
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

size: l Pull request size is large.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

⌂ 换网址