Skip to content
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

Improve registries documentation #429

Open
wants to merge 8 commits into
base: main
Choose a base branch
from

Conversation

vicroms
Copy link
Member

@vicroms vicroms commented Nov 18, 2024

This PR contains major changes to the registry's documentation:

  • Adds new sections to the registries concept article (preview)
    • Registry directory structure
    • Versions database
    • Built-in registry
    • Obtain git-tree SHA
    • Best practices for registries
  • Changes the registries reference article (preview)
    • Remove conceptual sections
    • Add JSON schema documentation for baseline.json and version files
  • Fix broken links generated by these changes

This comment was marked as outdated.

@vicroms vicroms marked this pull request as ready for review November 18, 2024 19:02

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.

Copy link
Member

@BillyONeal BillyONeal left a comment

Choose a reason for hiding this comment

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

The only thing this is 'request changes' over are the file format examples that are wrong, everything else is take it or leave it nitpicks.

vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/maintainers/registries.md Outdated Show resolved Hide resolved
| ---------- | ------ | ----------- |
| `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 |

Copy link
Member

Choose a reason for hiding this comment

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

I think we should add something like:

The version / verison-semver / version-date / version-string and port-version match the values in the port retrieved by the git-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.

Copy link
Member Author

Choose a reason for hiding this comment

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

Maybe we can add this to the "Recommended practices" section in the conceptual article.

vcpkg/maintainers/registries.md Outdated Show resolved Hide resolved
vcpkg/maintainers/registries.md Outdated Show resolved Hide resolved
vcpkg/maintainers/registries.md Show resolved Hide resolved

This comment was marked as outdated.

This comment was marked as outdated.

vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/concepts/registries.md Outdated Show resolved Hide resolved
vcpkg/maintainers/registries.md Outdated Show resolved Hide resolved
vcpkg/maintainers/registries.md Outdated Show resolved Hide resolved
vcpkg/maintainers/registries.md Outdated Show resolved Hide resolved
Co-authored-by: Robert Schumacher <[email protected]>
Co-authored-by: Billy O'Neal <[email protected]>

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Copy link
Contributor

Learn Build status updates of commit e95db83:

✅ Validation status: passed

File Status Preview URL Details
.markdownlint.jsonc ✅Succeeded
vcpkg/about/faq.md ✅Succeeded View
vcpkg/commands/add-version.md ✅Succeeded View
vcpkg/concepts/manifest-mode.md ✅Succeeded View
vcpkg/concepts/overlay-ports.md ✅Succeeded View
vcpkg/concepts/registries.md ✅Succeeded View
vcpkg/consume/boost-versions.md ✅Succeeded View
vcpkg/consume/classic-mode.md ✅Succeeded View
vcpkg/consume/git-registries.md ✅Succeeded View
vcpkg/consume/lock-package-versions.md ✅Succeeded View
vcpkg/consume/manifest-mode.md ✅Succeeded View
vcpkg/contributing/maintainer-guide.md ✅Succeeded View
vcpkg/get_started/overview.md ✅Succeeded View
vcpkg/maintainers/registries.md ✅Succeeded View
vcpkg/reference/vcpkg-configuration-json.md ✅Succeeded View
vcpkg/users/authentication.md ✅Succeeded View
vcpkg/users/config-environment.md ✅Succeeded View
vcpkg/users/examples/versioning.getting-started.md ✅Succeeded View
vcpkg/users/versioning-troubleshooting.md ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

Copy link

PRMerger Results

Issue Description
Changed Files This PR contains more than 10 changed files.
File Change Percent This PR contains file(s) with more than 30% file change.
Unapproved file extension(s) This PR contains file types that are not supported in the repo. The only supported file types are jpg, gif, png, json, svg and md.
Repository root file This pull request contains a file submitted to the root of the repository.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants