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 manifest] Add documentation! #13488

Merged
merged 12 commits into from
Sep 14, 2020
Merged

Conversation

strega-nil
Copy link
Contributor

@strega-nil strega-nil commented Sep 11, 2020

This adds documentation for manifest files and for manifest mode. It also converts the existing specification of the supports field to an EBNF, since I think that's easier to read and more exact.

There are two changes made to vcpkg manifests themselves as part of this documentation update:

  • $.features is now additionally allowed to be an object, and x-format-manifest will rewrite to this new object syntax.
  • x-format-manifest is now a non-experimental command

Example:

{
  "features": [
    {
      "name": "foo",
      "description": "bar"
    }
  ]
}

gets rewritten to

{
  "features": {
    "foo": {
      "description": "bar"
    }
  }
}

These are just for the maintainer docs,
not user docs.
this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.
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.

I'm not done reviewing yet; the thing I'm "request changes" over is the documentation of x- commands. In the case of x-set-installed IMO the previous explicit install/remove instructions were better for demonstrating how the tool works. In the case of x-format-manifest or similar, if we want users to use them, we should remove the x-.

docs/examples/patching.md Outdated Show resolved Hide resolved
docs/examples/packaging-zipfiles.md Outdated Show resolved Hide resolved
docs/examples/patching.md Show resolved Hide resolved
docs/maintainers/control-files.md Outdated Show resolved Hide resolved
docs/maintainers/maintainer-guide.md Outdated Show resolved Hide resolved
docs/maintainers/maintainer-guide.md Show resolved Hide resolved
docs/maintainers/pr-review-checklist.md Show resolved Hide resolved
docs/maintainers/pr-review-checklist.md Show resolved Hide resolved
docs/maintainers/pr-review-checklist.md Show resolved Hide resolved
docs/maintainers/pr-review-checklist.md Outdated Show resolved Hide resolved
@PhoebeHui PhoebeHui added the category:documentation To resolve the issue, documentation will need to be updated label Sep 14, 2020
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.

Thanks!

docs/examples/packaging-github-repos.md Outdated Show resolved Hide resolved
docs/examples/packaging-zipfiles.md Show resolved Hide resolved
docs/maintainers/manifest-files.md Outdated Show resolved Hide resolved
docs/maintainers/manifest-files.md Outdated Show resolved Hide resolved
docs/users/manifests.md Outdated Show resolved Hide resolved
docs/users/manifests.md Outdated Show resolved Hide resolved
docs/users/manifests.md Outdated Show resolved Hide resolved
docs/users/manifests.md Show resolved Hide resolved
@strega-nil strega-nil merged commit 0fec134 into microsoft:master Sep 14, 2020
@strega-nil strega-nil deleted the manifest-docs branch September 30, 2020 18:32
strega-nil added a commit to strega-nil/vcpkg that referenced this pull request May 5, 2021
* [vcpkg docs] add docs for manifest files

These are just for the maintainer docs,
not user docs.

* [vcpkg] EBNF-ify platform expression parsing

this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.

* [vcpkg docs] add manifest mode example

* [wip] docs for augustin

also fix tabs

* [vcpkg manifest] switch to using maps for features

* Apply suggestions from code review

* un-experimentize format-manifest

* flesh out the user manifest mode docs

* CRs

* billy CRs

* final personal pass-thru
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants