-
Notifications
You must be signed in to change notification settings - Fork 147
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC for Hosted Git Dependencies #79
Open
Volune
wants to merge
1
commit into
yarnpkg:master
Choose a base branch
from
Volune:hosted-git-dependencies
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
- Start Date: 2017-08-08 | ||
- RFC PR: | ||
- Yarn Issue: | ||
|
||
# Summary | ||
|
||
Clarify what is a *hosted* git dependency, which dependency patterns should be considered as *hosted*, and what are the differences with a regular git dependency. | ||
|
||
# Motivation | ||
|
||
*Hosted* git dependencies are dependencies hosted on Github, Gitlab or Bitbucket that can download the manifest and dependency content with a HTTPS request instead of using the `git` command. | ||
|
||
Because they are treated differently, they do not benefit from all the features of a regular git dependency (like yarnpkg/yarn#3553), or introduce some incompatibilities (yarnpkg/yarn#3923). | ||
Also these differences are poorly documented and hard to identify from the code. | ||
|
||
The **main goal** is to ensure that the same result can be expected by installing a *hosted* git dependency or a regular git dependency. | ||
|
||
Secondly, exhaustively document which patterns are resolved as *hosted* dependencies, what are the implications for private repositories, and how to write a pattern to be explicitly *regular*. | ||
Plus it would be nice to synchronise with `npm` (npm/hosted-git-info ?) | ||
|
||
At last, as much as possible, let the feature be extensible to other git hosts in the future (for example, self-hosted gitlab or bitbucket). | ||
|
||
# Detailed design | ||
|
||
As a first step, the existing implementation for *hosted* git dependencies should be removed, and patterns that previously matched a hosted dependency should resolve to a git repository. | ||
|
||
<small>Note: the alternative presented below would stop at this point.</small> | ||
|
||
When matching a *hosted* dependency pattern, the implementation must be able to resolve the host, user(team) name and repository name. | ||
The implementation must then provide the following urls: | ||
|
||
- url to download the git refs (branches and tags) | ||
- url to download the archive at a specific commit | ||
- url to download a file at a specific commit (used to download `package.json` or `yarn.json`) | ||
- a fallback git repository url (to be used if previous urls are not accessible, for example permission issue) | ||
|
||
The `Git` utility should be the only place to make a distinction between *hosted* repositories and other repositories.\ | ||
If it is a *hosted* repository, the `Git` utility should first try to make HTTPS requests, then fallback on using the `git` command. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could you add some examples for the workflow? The most important part of this RFC is to identify the rules for hosted/regular git dependencies. |
||
|
||
**TBD** Behaviour of `git import` with hosted dependencies. | ||
|
||
The following patterns should resolve to *hosted* dependencies: | ||
|
||
- `user/repo` (Github shorthand) | ||
- `protocol:user/repo` (protocol one of `github`, `gitlab`, `bitbucket`) | ||
- `git@hostname/user/repo` (hostname one of `github.com`, `gitlab.com`, `bitbucket.org`, `bitbucket.com`) | ||
|
||
The `.git` extension is optional. | ||
|
||
**TBD** What about `https://github.com/user/repo`, `git@hostname:user/repo` | ||
|
||
**TBD** Should `git:` protocol force a not-hosted mode? | ||
|
||
# How We Teach This | ||
|
||
Because all git dependencies will result in the same installed content regardless or the pattern (*hosted* or not), and some special cases are being removed, it should not be necessary to introduce the change to new or existing Yarn users. | ||
|
||
For advanced Yarn users, the documentation should describe the optimisations made for *hosted* dependencies, and the matching patterns. | ||
|
||
# Drawbacks | ||
|
||
The generated content in the lockfile and manifest will probably differ from the previous behaviour, that may break third-party tools. | ||
|
||
While the new implementation should be compatible with the currently installed packages, some edge cases of the old implementation may not be identified and become incompatible. | ||
|
||
# Alternatives | ||
|
||
- *What other designs have been considered?* | ||
|
||
Resolve *hosted* git patterns to regular git patterns and consider all git dependencies as being *regular*. | ||
It lacks optimisations, but doesn't require extra documentation and, maybe, can handle private repositories in a simpler way. It shares the same other drawbacks. | ||
|
||
- *What is the impact of not doing this?* | ||
|
||
Unexpected and/or undocumented behaviour | ||
|
||
# Unresolved questions | ||
|
||
- What will happen with private repositories (should fallback to `git` command) | ||
- What should be stored in the manifest and lockfile | ||
- Behaviour of `yarn import` | ||
- Exhaustive list of *hosted* dependency patterns | ||
- Differences with `npm` | ||
- How to differentiate the hash from the commit number and the hash from the downloaded tarball or git archive. (Should probably only use the commit number) |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could you justify why the code for hosted git dependencies should be removed?
Are there specific issues caused by the current implementation?
Can it be just modified?