RFC: introduce `volta list` and deprecate `volta current` #34

chriskrycho · 2019-05-15T18:00:21Z

Rendered RFC text. See earlier discussion at volta-cli/volta#349.

Add an informational command, volta list, replacing the volta current command and expanding on its capabilities. The list command will allow users to see their default and project-specific toolchains, and will support both human-friendly output and a tool-friendly output.

text/0000-informational-commands.md

chriskrycho · 2019-05-16T23:44:42Z

text/0000-informational-commands.md

+```sh
+$ volta list
+runtime node@v10.15.3 (default)
+packager yarn@v1.12.3 (default)


I'm unsure what we should actually output here: if the user has install-ed Yarn, presumably we should print it. Should we also always print the built-in npm? I currently lean toward yes; that would then extend to the human format as well. Thoughts?

I think printing the built-in npm is a good idea, along with what that version is

- identify whether the item is a runtime, a packager, or a tool - update the list to match the example user configuration

- use the correct invocation for plain, `--print=plain` - show both bare subcommand and `--all` for plain output

Co-Authored-By: Robert Jackson <me@rwjblue.com>

mikrostew

Awesome! Just a few comments on things I saw reading through this RFC.

(also, great use of <details> 😄 )

mikrostew · 2019-05-29T23:30:47Z

text/0000-informational-commands.md

+    - to runtimes: `volta list node`
+    - to packagers: `volta list yarn` (and, when custom installations of `npm` are supported, `volta list npm`)
+    - to a specific package: `volta list <package name>`
+    - to a specific tool: `volta list <tool name>`


These two options don't match the format below in "Details", which is:
volta list package <package>
volta list tool <tool>

Ah, good catch. Updated for consistency, though depending on how we sort out the related question I may have to update it the other direction. 😆

text/0000-informational-commands.md

mikrostew · 2019-05-29T23:53:15Z

text/0000-informational-commands.md

+```sh
+$ volta list
+runtime node@v10.15.3 (default)
+packager yarn@v1.12.3 (default)


I think printing the built-in npm is a good idea, along with what that version is

text/0000-informational-commands.md

mikrostew · 2019-05-30T00:02:34Z

text/0000-informational-commands.md

+For the TypeScript config specified in the canonical example:
+
+```sh
+volta list package typescript --human


Slight discrepancy here between volta list <package> and volta list package typescript.

This will probably need to be volta list package <package> and volta list tool <tool> to be able to disambiguate when packages and tools have the same names (like the create-react-app example).

This is actually the reason why I had volta list package <package> and volta list tool <tool> in an earlier draft of the RFC. I'm back-and-forth on it, because in the case you identified, it's the same output either way. In a case where there's more than one binary, but one does match the package name, I don't think it harms anything to default to the package in that case? 🤔 But I'm very willing to be persuaded here—I just found myself leaning slightly in the direction of brevity!

After thinking about this more, I like the volta list <package-or-tool> approach, where it defaults to the package. It's more compact to type, and in cases where the binary and the package are the same name, you get more information.

mikrostew · 2019-05-30T00:07:56Z

text/0000-informational-commands.md

+
+    - all available package binaries?
+    - a subset of package binaries once the number crosses a threshold, with instructions about how to see all?
+    - no package binaries?


Currently the only way to create a shim for a binary is to use volta install <package>, which installs the package and shims any of the installed binaries. Then the shim will intercept any invocation inside of a project to detect if it is a package binary.

Since this is already displaying the available binaries (from installed packages), the available package binaries will be a subset of that, and could probably be displayed with some indication that they are coming from the current project.

This plus your suggestion below make a ton of sense to me; I'll update the design accordingly and at least the initial implementation will work that way.

mikrostew · 2019-05-30T00:11:53Z

text/0000-informational-commands.md

+    - a subset of package binaries once the number crosses a threshold, with instructions about how to see all?
+    - no package binaries?
+
+    And how should that be presented in `plain` vs. `human` mode? Should there be any differences between `plain` and `human` for the bare command (as in the current design)?


My first thought at this would be the addition of a single line (if for instance the project uses ember):

$ volta list --human ⚡️ Currently active tools: Node: v8.16.0 (current @ ~/node-only/package.json) Yarn: v1.12.3 (default) Tool binaries available: create-react-app, tsc, tsserver ember (current @ ~/node-only/package.json)

I like that design a lot. Should the previous line then include (defaults) to distinguish them? 🤔

I think having (defaults) for the first is a great idea to make the distinction obvious

charlespierce

This is awesome and incredibly detailed! I don't have any substantive comments on the command itself, just a few comments around the edges.

charlespierce · 2019-05-31T17:26:28Z

text/0000-informational-commands.md

+
+## Use another command name
+
+As noted in [**Why `list`?**][why-list], options for this subcommand name include `list`, `ls`, `tools`, `toolchain`, `info`, and `current`. (For discussion of shorthands, see the next section.) Given the considerable [prior art][prior-art] using `list`, however, it seems the best option in terms of what users will expect.


I like the idea (first mentioned in Discord I believe) of having ls be a full alias of list, just for ergonomic reasons. It doesn't have to be documented or shown anywhere, just as a bonus for usability & potential discoverability of the command.

charlespierce · 2019-05-31T17:28:05Z

text/0000-informational-commands.md

+
+## Deprecating `volta current`
+
+Since `volta list` subsumes (and substantially extends upon) the functionality of `volta current`, `volta current` should be deprecated when `volta list` is implemented. The deprecation should include a warning that the command will be removed in a future version and information about how to use `volta list --current <tool>` as a replacement.


I like this approach a lot, it allows us to introduce the command and the deprecation warning without a breaking change, and then the next time we have a breaking change we can take that opportunity to remove the current command (that I suspect no one is using anyway given its limited functionality).

charlespierce · 2019-05-31T17:34:12Z

text/0000-informational-commands.md

+- Should the command accept flags to narrow the search instead of a positional argument, e.g. `volta list --node`, `volta list --yarn`, `volta list --package=typescript`, etc.?
+
+- How should the built-in version of `npm` be displayed to the user? Options include:
+    - associated with the runtime it ships with, e.g. `v12.2.0 (with npm v6.4.1)`


This is how we currently show it when you run e.g. volta install node, so if possible it would be good to align with that. Also, until we implement the volta install npm logic, listing npm as a separate packager seems like it has the potential for confusion, implying that the user can manage npm themselves.

- Go back to using `(default|current @ <path>|fetched)` as the design for indicating the origin of a given item, but with the simplifications made for packages in the previous commit. - Add an example for local package overrides.

mikrostew · 2020-06-10T21:01:01Z

Now that volta-cli/volta#461, volta-cli/volta#701, and volta-cli/volta#697 have landed, is this RFC ready to be merged? Should we wait for volta-cli/volta#659?

chriskrycho · 2020-06-22T03:08:03Z

I think this is quite ready to merge. We may continue to add more output formats and to iterate on the design as we find pain points, but the RFC has served its purpose and is fully implemented given our existing constraints from where I stand!

rwjblue reviewed May 16, 2019

View reviewed changes

text/0000-informational-commands.md Outdated Show resolved Hide resolved

text/0000-informational-commands.md Show resolved Hide resolved

text/0000-informational-commands.md Outdated Show resolved Hide resolved

chriskrycho commented May 16, 2019

View reviewed changes

chriskrycho force-pushed the info-commands branch 4 times, most recently from 03237ad to 751a726 Compare May 29, 2019 16:10

chriskrycho marked this pull request as ready for review May 29, 2019 16:13

chriskrycho mentioned this pull request May 29, 2019

Implement volta list command volta-cli/volta#461

Merged

17 tasks

chriskrycho and others added 22 commits May 29, 2019 13:52

volta list: create RFC and write summary paragraph.

a04d832

volta list: first pass at deprecation text for current.

0a486f5

volta list: include survey of prior art.

94ab274

volta list: elaborate prior art.

716a84d

volta list: start iterating on list design.

81ce768

volta list: tweak printing mode to use --print=plain|pretty.

6a3151a

volta list: define the user’s config for worked examples.

f41b7bd

volta list: improve proposed output from bare subcommand.

e790d77

volta list: improved design for parse-friendly "plain" format.

4228594

- identify whether the item is a runtime, a packager, or a tool - update the list to match the example user configuration

volta list: design a "pretty" output for --all invocation.

074dc5a

volta list: more (correct) details for --plain output

e169393

- use the correct invocation for plain, `--print=plain` - show both bare subcommand and `--all` for plain output

volta list: add an unresolved question about the bare subcommand

10a8f2d

volta list: correct a typo in user config description

2123fea

Co-Authored-By: Robert Jackson <me@rwjblue.com>

volta list: remove a typo

5260940

volta list: fix a path in an example for bare subcommand

ccff706

volta list: use "tools" and "binaries" verbiage consistently.

a99ce7a

volta list: pretty format for bare subcommand

babbe63

volta list: pretty output for --all flag.

9a35372

volta list: use "human" instead of "pretty"

6b3ea90

volta list: use actual project path and simplify example paths

8daf0d5

volta list: restructure to put overall command design first

35c9579

volta list: correctly punctuate a sentence

eb9d1ad

chriskrycho added 2 commits May 29, 2019 16:01

volta list: drop now-answered question

96237b8

volta list: fix a mistake in Pedagogy section

64ee04d

mikrostew reviewed May 30, 2019

View reviewed changes

chriskrycho added 4 commits May 30, 2019 08:11

volta list: fix human format for bare volta list

5c41ddd

volta list: standardize on --print=<style>

67e5116

volta list: drop tool and package from Details.

2441c1c

volta list: fetched-only tools do not have platforms

a0c5207

charlespierce reviewed May 31, 2019

View reviewed changes

chriskrycho added 7 commits June 18, 2019 10:52

volta list: use --format= instead of --print=

ee8e9ad

volta list: add note about future possible formats

a90df5e

volta list: add --current and --default flags

5b75f0a

volta list: add design for list node and list <packager>

10a9fb0

volta list: fix shell script code samples

6ffb792

volta list: update table of contents with latest structure

611903c

volta list: make list <package> and list <tool> output consistent

9df21a2

chriskrycho force-pushed the info-commands branch 2 times, most recently from 04a3e33 to b629a9a Compare June 21, 2019 22:57

volta list: use "package manager" instead of "packager"

0dba88c

chriskrycho force-pushed the info-commands branch from b629a9a to 0dba88c Compare June 21, 2019 23:07

chriskrycho added 2 commits July 31, 2019 12:11

volta list: update fetched-only output and drop ⚡.

60f9d96

volta list: iterate on source; add current package.

a38c96a

- Go back to using `(default|current @ <path>|fetched)` as the design for indicating the origin of a given item, but with the simplifications made for packages in the previous commit. - Add an example for local package overrides.

chriskrycho force-pushed the info-commands branch from cf0d266 to a38c96a Compare July 31, 2019 18:35

volta list: support printing tools specifically

e43144f

chriskrycho mentioned this pull request Aug 14, 2019

implement volta list --format=human volta-cli/volta#523

Closed

charlespierce changed the base branch from master to main June 15, 2020 17:31

charlespierce merged commit cbb8525 into main Jul 15, 2020

charlespierce deleted the info-commands branch July 15, 2020 19:19

chriskrycho mentioned this pull request Feb 7, 2023

update all package volta-cli/volta#1440

Open


		## Use another command name

		As noted in [Why `list`?][why-list], options for this subcommand name include `list`, `ls`, `tools`, `toolchain`, `info`, and `current`. (For discussion of shorthands, see the next section.) Given the considerable [prior art][prior-art] using `list`, however, it seems the best option in terms of what users will expect.


		## Deprecating `volta current`

		Since `volta list` subsumes (and substantially extends upon) the functionality of `volta current`, `volta current` should be deprecated when `volta list` is implemented. The deprecation should include a warning that the command will be removed in a future version and information about how to use `volta list --current <tool>` as a replacement.

RFC: introduce volta list and deprecate volta current #34

RFC: introduce volta list and deprecate volta current #34

Uh oh!

Conversation

chriskrycho commented May 15, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikrostew left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chriskrycho May 30, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

charlespierce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikrostew commented Jun 10, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chriskrycho commented Jun 22, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

RFC: introduce `volta list` and deprecate `volta current` #34

RFC: introduce `volta list` and deprecate `volta current` #34

chriskrycho commented May 15, 2019 •

edited

Loading

chriskrycho May 30, 2019 •

edited

Loading

mikrostew commented Jun 10, 2020 •

edited

Loading