Improve registries documentation #429
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
PRMerger Results
|
| * A directory named `ports`, contains the collection of ports, with each | ||
| subdirectory containing a specific port matching the subdirectory name. For | ||
| example, the files for port `foo` must be located in `ports/foo`. |
There was a problem hiding this comment.
This is not actually true for Git registries, do we care about the distinction?
There was a problem hiding this comment.
It is not required by filesystem registries either since the version files are the ones that resolve each version's path. But I think it is better to document a recommended layout.
|
|
||
| ## Versions database | ||
|
|
||
| All registries, regardless of their kind, must contain a `versions` folder at the |
There was a problem hiding this comment.
| All registries, regardless of their kind, must contain a `versions` folder at the | |
| All registries contain a `versions` directory at the |
There was a problem hiding this comment.
Given that we are describing to users what registries are, rather than describing what behavior something implementing registries must do, I think we should describe them with present tense, as in "registries contain a versions directory" rather than "registries must contain a versions directory". I think we should reserve 'must' for things the user has to do rather than things vcpkg does.
I also suggest 'directory' rather than 'folder' everywhere, as 'folder's can be non-directories like the network browser or control panel, but we really need them to be directories.
There was a problem hiding this comment.
I see you're already doing this in most places.
There was a problem hiding this comment.
Given that we are describing to users what registries are, rather than describing what behavior something implementing registries must do, I think we should describe them with present tense, as in "registries contain a versions directory" rather than "registries must contain a versions directory". I think we should reserve 'must' for things the user has to do rather than things vcpkg does.
I agree with this recommendation, I'll revise the document.
| * A directory named `versions` must contain the files that comprise the [versions | ||
| database](#versions-database). |
There was a problem hiding this comment.
This is not technically true for built-in registries, do we care? Ditto below everywhere we talk about this being required.
| | ---------- | ------ | ----------- | | ||
| | `git-tree` | string | A Git calculated SHA used to retrieve the port version | | ||
| | [`version`<br>`version-semver`<br>`version-date`<br>`version-string`](../reference/vcpkg-json.md#version) | string | Upstream version information | | ||
| | [port-version](../reference/vcpkg-json.md#port-version) | integer | Port files revision | | ||
|
|
There was a problem hiding this comment.
I think we should add something like:
The
version/verison-semver/version-date/version-stringandport-versionmatch the values in the port retrieved by thegit-tree. For example:PS D:\vcpkg> Get-Content D:\vcpkg\versions\c-\curl.json -TotalCount 7 { "versions": [ { "git-tree": "6ef1763f3cbe570d6378632c9b5793479c37fb07", "version": "8.11.0", "port-version": 1 }, PS D:\vcpkg> git show 6ef1763f3cbe570d6378632c9b5793479c37fb07:vcpkg.json | Select-Object -First 5 { "name": "curl", "version": "8.11.0", "port-version": 1, "description": "A library for transferring data with URLs",
I'm torn on whether this is a 'must' situation. It's true that if a user is manually doing this they must ensure that they do this, but it's also true that we provide tooling that makes this an implementation detail most of the time.
| }, | ||
| "port-b": { | ||
| "baseline": "19.00", | ||
| "my-baseline": { |
There was a problem hiding this comment.
I think this was better before when my-baseline was clearly a baseline revision rather than my-baseline.
| "version": "2.6.3", | ||
| "port-version": 0, | ||
| "path": "$/ports/kitten/2.6.3_0" | ||
| "git-tree": "$/ports/foo/1.1.0", |
There was a problem hiding this comment.
| | ---------- | ------ | ----------- | | ||
| | `path` | string | The filesystem location where the port files for the corresponding version are located | | ||
| | [`version`<br>`version-semver`<br>`version-date`<br>`version-string`](../reference/vcpkg-json.md#version) | string | Upstream version information | | ||
| | [port-version](../reference/vcpkg-json.md#port-version) | integer | Port files revision | | ||
|
|
There was a problem hiding this comment.
Ditto showing an example that these need to match might be nice.
Co-authored-by: Billy O'Neal <[email protected]>
|
Learn Build status updates of commit efd1918: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
PRMerger Results
|
This PR contains major changes to the registry's documentation:
git-treeSHA