CLI Feedback
What have you loved?
Love the ability to opt-in to api preview features!
What was confusing or gave you pause?
Docs for the api --preview flag is a little unclear. The extent of the manpage docs for --preview is:
-p, --preview=[] Opt into GitHub API previews
And an example:
# opt into GitHub API previews
$ gh api --preview baptiste,nebula ...
My confusion is that listing of available preview features use foo-preview as the full name for the preview (including the -preview suffix). But the examples in the docs do not. It isn't clear if the -preview suffix is required, optional or disallowed.
After digging up the initial PR: #3077, (in particular the description):
Before:
gh api -H 'Accept: application/vnd.github.nebula-preview+json, application/vnd.github.baptiste-preview, application/vnd.github.squirrel-girl-preview'
Now:
gh api -p nebula,baptiste -p squirrel-girl
It starts to become clear that the baptiste,nebula examples in the manpage docs are not just placeholders but examples of actual preview features, and so presumably the -preview suffix may be omitted. But I'm still not entirely sure if it's optional or actually disallowed. If I do gh api --preview foo-preview will that end up using a preview header of application/vnd.github.foo-preview-preview+json? 🤷
Are there features you'd like to see added?
I would suggest clarifying the docs for the --preview option that the preview strings may (or must?) omit the -preview suffix.
I would even suggest including a link to the Preview Features listing right in the docs for that flag. It would be super handy to be able to jump straight there from the terminal. https://docs.github.com/en/rest/overview/api-previews
Followup
After some experimentation it seems the -preview suffix must be omitted. (My api calls using --preview ant-man-preview seemed to operate as if wasn't using the preview flag at all.) So a followup request would be to make the -preview suffix optional but still acceptable if provided. I expect it will be quite likely for people to copy the preview feature names directly from the list and paste them; without carefully trimming the suffix.
CLI Feedback
What have you loved?
Love the ability to opt-in to api preview features!
What was confusing or gave you pause?
Docs for the
api --previewflag is a little unclear. The extent of the manpage docs for--previewis:And an example:
My confusion is that listing of available preview features use
foo-previewas the full name for the preview (including the-previewsuffix). But the examples in the docs do not. It isn't clear if the-previewsuffix is required, optional or disallowed.After digging up the initial PR: #3077, (in particular the description):
It starts to become clear that the
baptiste,nebulaexamples in the manpage docs are not just placeholders but examples of actual preview features, and so presumably the-previewsuffix may be omitted. But I'm still not entirely sure if it's optional or actually disallowed. If I dogh api --preview foo-previewwill that end up using a preview header ofapplication/vnd.github.foo-preview-preview+json? 🤷Are there features you'd like to see added?
I would suggest clarifying the docs for the
--previewoption that the preview strings may (or must?) omit the-previewsuffix.I would even suggest including a link to the Preview Features listing right in the docs for that flag. It would be super handy to be able to jump straight there from the terminal. https://docs.github.com/en/rest/overview/api-previews
Followup
After some experimentation it seems the
-previewsuffix must be omitted. (My api calls using--preview ant-man-previewseemed to operate as if wasn't using the preview flag at all.) So a followup request would be to make the-previewsuffix optional but still acceptable if provided. I expect it will be quite likely for people to copy the preview feature names directly from the list and paste them; without carefully trimming the suffix.