docs: Added a Yarn Berry package manager design documentation#1586
docs: Added a Yarn Berry package manager design documentation#1586mohamedbouchtout wants to merge 9 commits into
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive design document for Yarnberry (Yarn 2+) integration in Hermeto, detailing dependency resolution, prefetching, offline caching, and security considerations regarding plugins and arbitrary code execution. The review feedback focuses on improving the document's quality by correcting typos and aligning the tone with the professional senior technical writer style guide, specifically by using imperative mood, removing conversational phrasing, and avoiding first-person pronouns.
|
|
||
| The path to the patch file can be parsed from the | ||
| [locator](https://github.com/chmeliik/berryscary/blob/c424d96e1e36542e52985aee716e1b12881c24fb/yarn.lock#L740). | ||
| We may want to set a reasonably large upper limit for the size of the patch file. |
There was a problem hiding this comment.
To adhere to the documentation style guide, use imperative mood language when describing design decisions or requirements.
| We may want to set a reasonably large upper limit for the size of the patch file. | |
| Set a maximum size limit for patch files to prevent excessive resource consumption. |
References
- Use imperative mood language (link)
|
|
||
| #### [Installing Yarnberry][yarn-install-guide] | ||
|
|
||
| As we’ve thoroughly established earlier, Hermeto will depend on Yarnberry to populate the offline cache. How can we install Yarnberry in the Hermeto container? Even better, how can we make sure we always have exactly the same version as the user? (And is that actually a good idea?) |
There was a problem hiding this comment.
To align with a professional senior technical writer persona, avoid conversational phrasing and rhetorical questions. State the design requirements directly and objectively.
| As we’ve thoroughly established earlier, Hermeto will depend on Yarnberry to populate the offline cache. How can we install Yarnberry in the Hermeto container? Even better, how can we make sure we always have exactly the same version as the user? (And is that actually a good idea?) | |
| Hermeto depends on Yarnberry to populate the offline cache. The Yarnberry installation in the Hermeto container must match the version specified by the project to maintain consistency. |
References
- You are a professional senior technical writer persona (link)
| **So, what does this mean for us?** | ||
|
|
||
| We need to make some decisions. |
There was a problem hiding this comment.
The heading and transition are very conversational. To align with a professional senior technical writer persona, use a formal heading.\n\nSuggested change:\nmarkdown\n### Design Considerations\n
References
- You are a professional senior technical writer persona (link)
| - Corepack allows the user to specify the expected checksum. That protects the user (so we should recommend it), but does not protect us from a malicious user. | ||
| - And even if the answer is yes, is it OK to do the prefetch using a dynamically fetched version of Yarnberry? For what it’s worth, it shouldn’t hurt reproducibility (quite the opposite, given that the version is pinned in package.json). | ||
|
|
||
| For now, I will assume a **1-No, 2-Yes situation**: |
There was a problem hiding this comment.
Avoid first-person pronouns ("I") and conversational phrasing to maintain a professional senior technical writer persona.
| For now, I will assume a **1-No, 2-Yes situation**: | |
| The following approach addresses these concerns: |
References
- You are a professional senior technical writer persona (link)
| 3. When running any `yarn` commands, make sure to set the ignorePath option (or the YARN_IGNORE_PATH variable) to use the global `yarn` rather than the local one | ||
| 4. And that’s it. | ||
|
|
||
| **And what does it mean for the user?** |
There was a problem hiding this comment.
The heading is very conversational. To align with a professional senior technical writer persona, use a formal heading.\n\nSuggested change:\nmarkdown\n### User Requirements\n
References
- You are a professional senior technical writer persona (link)
mohamedbouchtout
force-pushed
the
doc-standarization
branch
from
b671c86 to
2e022d8
Compare
There was a problem hiding this comment.
I am yet to do a deep-dive review on this, but for the purposes of reviewing an old doc (that partially predates my involvement with the project) seeing this PR split into distinct chunks starting with the original and then gradually updating it until it actually reflects our logic is a nice take that I as a reviewer appreciate in this particular case! However, before we merge this all commits should be squashed to a single one because we're adding a single (presumably) complete document.
Created a design doc for the yarn berry package manager by taking a existing google doc and changing it's format to match the HERMETO/docs/design/package-manager-template.md template while keeping the exact same content. Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
This section was created when some features were in scope and some weren't. This is no longer needed as we support all yarn versions at the same time. Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
Zero-installs is no longer supported and updated the doc to reflect that. Use commit 0a91337 (hermetoproject@0a91337) as reference. Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
Hermeto will raise a UnsupportedFeature error since git deps are no longer supported. Use this method as reference (https://github.com/hermetoproject/hermeto/blob/13b2f047f7b13a42116acaf2b9f18e6fd211a788/tests/unit/package_managers/yarn/test_locators.py#L72). Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
Removed all cachito reference similar to with the whole Hermeto project. replaced the json example with a NPM one from (https://github.com/hermetoproject/hermeto/blob/main/tests/unit/package_managers/yarn/test_resolver.py#L52). Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
This feature was added in commit 4492b38 (hermetoproject@4492b38). This commit explains well the workspace feature for yarn v4. The _resolve_yarn_project() and _fetch_dependencies() methods contain most of the functionality updates. Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
Added the proxy support to the doc using the commit 48e5156 (hermetoproject@48e5156a17) as refernce. Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
This feature handles the NotAGitRepo exception as explained in commit ebc895b (hermetoproject@ebc895b). Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
This feature was added to help prevent TLS verification failures as mentioned in the commit b4e28ff (hermetoproject@b4e28ff865). Signed-off-by: Mohamed Bouchtout <mbouchto@redhat.com>
mohamedbouchtout
force-pushed
the
doc-standarization
branch
from
2e022d8 to
50ceb3a
Compare
3 participants
Summary
This PR introduces docs/design/yarnberry.md covering Yarn Berry's architecture, developer workflow, dependency resolution, lockfile format, plugin system, and how Hermeto processes Yarn Berry projects. The document follows the standard design doc template and has been updated to match the current codebase, removing references to features that are no longer supported and adding documentation for features introduced since the original doc was written.
Details
UnsupportedFeatureerror.