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

[vcpkg] Add initial versioning documentation #15565

Merged
merged 12 commits into from Jan 15, 2021

Conversation

ras0219
Copy link
Contributor

@ras0219 ras0219 commented Jan 11, 2021

This PR brings versioning into a near-ship state:

  1. Adds reference documentation for the experimental user-facing features of versioning.
  2. Renames $x-default-baseline to builtin-baseline and adds proper parsing support
  3. Improves error messages throughout the versioning experience to help guide users to success
  4. Improves performance of versioning to avoid all git manipulation in the happy path.
  5. Uses git archive to achieve high performance git tree checkouts.
  6. Improved test coverage of versioning
  7. Users without any versioning fields will not experience any behavior changes with the versions feature flag enabled (+test).
  8. Remove version=.

Two issues not addressed in this PR:

  1. Emit warnings if the user uses overrides or constraints in a top-level manifest and doesn't have a baseline set (the user won't get versioning behavior in this case and that could be surprising)
  2. Overrides currently uses schemed field names, however those schemes have no semantic meaning.

The initial spec is in #11758. Convenience link to the new docs is: https://github.com/ras0219/vcpkg/blob/dev/roschuma/versions/docs/users/versioning.md.

For local experiments, you will need to pull in versioning files:

git pull https://github.com/ras0219/vcpkg dev/roschuma/version-files

Example:

As an example, you can try:

{
    "name": "example",
    "version-date": "2020-01-01",
    "builtin-baseline": "334ba25e577b83331d5cfeb14d65768553ea1d9e",
    "dependencies": [
        {
            "$comment": "Note that this old rapidjson uses version-string",
            "name": "rapidjson",
            "version>=": "2019-06-28"
        },
        "zlib"
    ],
    "overrides": [
        {
            "name": "rapidjson",
            "version-string": "2019-06-28"
        }
    ]
}

and in that directory

vcpkg install --feature-flags=manifests,versions
vcpkg list --feature-flags=manifests,versions

Observing the result of 2019-06-28 and 1.2.11#9 for rapidjson and zlib respectively. If you didn't pull in the version files, you should see an error message like:

Failed at [/workspaces/vcpkg/toolsrc/src/vcpkg/registries.cpp(296)] with message:
Error: Couldn't find explicitly specified baseline `"334ba25e577b83331d5cfeb14d65768553ea1d9e"` in the baseline file, and there was no baseline at that commit or the commit didn't exist.
Error: while checking out baseline '334ba25e577b83331d5cfeb14d65768553ea1d9f:port_versions/baseline.json':
fatal: Path 'port_versions/baseline.json' does not exist in '334ba25e577b83331d5cfeb14d65768553ea1d9f'

This may be fixed by updating vcpkg to the latest master via `git pull`.
The current commit is "efe40c8c882c2bf3125b27e10294089f94e7b87b"

or

Failed at [/workspaces/vcpkg/toolsrc/src/vcpkg/install.cpp(877)] with message:
Error: no version entry for rapidjson at version 2019-06-28.
We are currently using the version in the ports tree (2020-09-14), since no rapidjson.json was found in /port_versions.

@JackBoosY JackBoosY added category:documentation To resolve the issue, documentation will need to be updated category:vcpkg-feature The issue is a new capability of the tool that doesn’t already exist and we haven’t committed info:internal This PR or Issue was filed by the vcpkg team. labels Jan 11, 2021
@ras0219 ras0219 force-pushed the dev/roschuma/versions branch 8 times, most recently from ac89dfe to 434fd06 Compare January 11, 2021 19:45
docs/users/versioning.md Outdated Show resolved Hide resolved
docs/users/versioning.md Outdated Show resolved Hide resolved
docs/users/versioning.md Outdated Show resolved Hide resolved
docs/users/versioning.md Outdated Show resolved Hide resolved
@ras0219
Copy link
Contributor Author

ras0219 commented Jan 13, 2021

I've added support for { "name": "zlib", "version>=": "1.2.11#8" } via the comment banners SUPPORT_HASH_SYNTAX; once the bikeshed has been painted, we can delete any offending code.

@ras0219-msft ras0219-msft merged commit 4f8fb51 into microsoft:master Jan 15, 2021
@ras0219 ras0219 deleted the dev/roschuma/versions branch January 15, 2021 20:35
strega-nil pushed a commit to strega-nil/vcpkg that referenced this pull request May 5, 2021
* [vcpkg] Improve efficiency and tests of versioning

* [vcpkg] Add initial versioning documentation and rename x-default-baseline to builtin-baseline

* [vcpkg] Enable metrics for builtin-baseline & overrides

* [vcpkg] Address PR comments

* [vcpkg] Add support for  syntax in version>=

* [vcpkg] Remove port-version from dependency syntax

* [vcpkg] Address CR comment

* [vcpkg] Minor docs fixup
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
category:documentation To resolve the issue, documentation will need to be updated category:vcpkg-feature The issue is a new capability of the tool that doesn’t already exist and we haven’t committed info:internal This PR or Issue was filed by the vcpkg team.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants