-
-
Notifications
You must be signed in to change notification settings - Fork 5
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
CLI feature set #129
Comments
So basically a wishlist of which features we would like the CLI/GUI to have? Would you like us to respond in this issue, or in the mentioned issues? |
Yepp. And what it look like to be the best possible (most consistent, least surprising) user experience.
Let's discuss it here. |
Okay. Let me kick-off things then. CLIIn general, I'd like the CLI to help me with:
Fetching an exercise
Submitting an exercise
Showing progress
GUIFor the GUI, its most important tasks to me are:
Displaying solutions
The above items will (of course) have to take into account what solutions you are allowed to see. Displaying comments
Displaying language track documentation
Displaying general documentation
In general, this is mostly how things already work, with some more polishing. One particular aspect I would really like to see improved, is the discovery of data. At the moment, it is not doable to quickly show all comments I made. In general, there should be overview pages for exercises and comments, with several filtering options to drill-down. |
This is a list of current, relevant, commands for the exercism CLI:
From the CLI standpoint, the features you've requested are there we just need to polish them and their outputs. Also, it would help a lot to have the command names match what they do. We could also take this time to work on a v2 of the CLI so it's a bit easier to iterate over. |
Yes, me too. I think that we should consider what it would mean for someone to do all discovery via the CLI rather than through the website (we should make both possible, of course).
@ErikSchierboom Do you mean the website, or the GUI which is the equivalent of the CLI (on the user's local machine)?
I would love that, and would be happy to implement a v3 of the API (all in http://exercism.io/api/v3, rather than having two different domains that we talk to). Also I'd love to use spf13/cobra for that. I've come to like it better than the one we're using. I'd like to have a We might consider whether there's a level between We might also want to consider whether a Another potential thing to think about is providing an I'd like all of the user-facing text (error messages, confirmation messages, notices) to come from the API so that we can easily change these without having to release a new client. This will also let us do A/B testing on the copy. I think that we should consistently require people to specify which track they're acting on (except when saying which tracks are available), and only act on one track at a time. We're only going to get more and more tracks, and more and more exercises, so if we act on all the tracks, that's guaranteed to develop performance problems. When delivering files (either from the CLI/GUI to the API or from the API to the CLI/GUI) I think we should do chunked transfers of zip files. That would avoid our current problems with encoding (can't send binary in a JSON file) as well as problems with performance when acting on multiple exercises in a single track (we're only ever going to get more exercises). For error messages, we should always tell people what is wrong and how to fix it. Since the how to fix it will depend on whether it's the CLI or the GUI, we will need to account for having the main text in the API, and provide some way to interpolate known values on the client side. |
Some thoughts about fetching exercises, based on the above thoughts, as well as comments from @petertseng in exercism/cli#369 If we can infer what the person wants to fetch based on the current directory, then we should do so. If we can't then we should provide an error message and suggest how to fix it (either by changing directory, or specifying flags). If we make it so that people take an explicit action in order to start a track, then for many people To do this, we would need to store the fact that they've explicitly chosen to start a track independently of them submitting their first exercise (because they might not submit an exercise, even though we know they've chosen to do that). We'd need to store this on the server side of things, because people use multiple computers (e.g. work and personal). In other words, by making This also makes sense, because we support having global track-level files (one-time setup stuff for files that they would need to use across all the exercises, such as a testing library or package config). This in turn also opens up the possibility of having a track-level tutorial, interactively walking people through the step-by-step, hand-hold-y version of how to do TDD etc.
Assuming that someone has started just one track, say Haskell, then we can assume that the CLI knows this. We should consider whether we prefer options or flags for fetching a specific exercise. E.g.
Use the
This is an interesting one. What is the ideal name to distinguish between all and the ones I've previously fetched? My first thought is
And do we store this on the server side so that people could fetch everything they've already fetched on a different computer? I would posit that for consistency we should use If we want to overwrite, then use A related question is how we let people fetch their solution. We can infer the exercise from the directory, or accept a flag or both, but it gets weird:
The default behavior for And related to that, how do people specify that they want all the submitted solutions in a track?
The other question about solutions is whether or not we submit the test file as well. When people set up the track locally, we can put the pattern in the config file that the CLI reads, and always submit it. On the website we could collapse the file in the UI so that it's minimized by default. This would remove the need to have versioning. People submit whatever version they want. Or we could use a different type of versioning that only the CLI cares about, in order to warn people that a new version of the exercise is available, and would they like to fetch it and update their existing solution. |
Another flag to consider is |
Thinking more about this, I'd really like to consider the implication of versioning the exercises in such a way that only the app and the client know the version, but that it doesn't affect the actual test and solution files. We could store which version of a test suite someone has last submitted on the backend, which would let us tell the user about updated test suites either in the app or via the client. There are some interesting questions around diffing and overwriting new versions of test suites in exercism/cli#362 |
I'm pretty lazy and like to type less, so it is good if arguments can be inferred, and if there is no chance of positional ambiguity then positional args are good. Looks like these are the main things I use the CLI for:
To me, it's not going to be a big deal if any of these features don't make it in. I would edit them into my local copy or write wrapper scripts that do it. |
Hi. I've just started using another feature of the CLI:
|
@petertseng How often do you fetch specific slugs? When you do, where did you get the slug name? (list from the CLI? memory? The website?) Would you be OK with I think we can probably do positional arguments, but it's going to be tricky because we have both tracks and slugs. If we always infer the track, though, and error if we can't, then maybe we could use the positional argument for the slug without too much confusion. |
Every time I fetch (I can't put a specific frequency on how often I fetch, but I think the relative frequency is what's important to the question anyway). I know that I will never use the
I used to use the website, but these days I prefer the colour-coded (above)
As long as the API allows requesting a specific track+exercise, I imagine I will always say "yes, OK", because if the CLI's arguments do not exactly match my preferences I will simply modify my copy of the CLI until they do, or make a wrapper script that matches. So, |
:-) I think it's worth figuring out how people currently use the CLI, because I imagine that a lot of people would have your same preferences, but not be able to modify the CLI |
It's a tough question because I can't really be sure how widespread my preferences are. When I was younger I used to overestimate, but it's possible I've overcompensated for that by now and am now underestimating. My reasoning is: Because for my uses a single argument to This does get tricky with the two-argument form (both exercise and track are specified). It's actually not useful for me because I know I will always cd into the track directory before fetching (allowing the track to be inferred from my current directory). But suppose someone opens the exercise files in an IDE and only opens a terminal to fetch. That person would probably not want to cd into the track directory and would instead want to be able to specify the track. Then the interesting question is should that be specified as (I know, there was talk about inferring the track by keeping something server-side, but I think at some point someone will ask for a way to specify both track and exercise in one command?) |
I think that for the track it makes sense to infer it if we can, and then allow the use of a flag ( |
As part of the new redesign, a lot will change on the website, and we'd like to tweak the CLI to feel more streamlined as well. One big change that we want to make is to use the terminology So This raises the question what do we call it when you're downloading someone else's solution to play with it locally? |
It would be possible to overload the term.
It would be possible, but I haven't expressed an opinion on whether it would be a good idea. |
Hm. Yeah, it would be possible. My gut feeling about it is that I'd rather not, but I don't know that I can make a cogent argument about why we shouldn't overload it. Maybe if we always passed a URL if we meant someone else's solution it might feel different. Not sure. |
I'd like to be able to submit from a path that's a symbolic link to the configured exercism path. Nice-to-have. |
@wobh Would you open an issue in the CLI repository about the symlink thing and describe your use case? I think that it shouldn't be hard to implement. |
Ok, everyone. I've gone through the discussion in detail, and the various linked issues, and I've tried to come up with a suggested user interface for a small initial feature set for the Nextercism launch. Proposal: Nextercism CLIFor the beta launch I suggest focusing on a minimal feature set:
Before the public launch, we should flesh this out to include Aliases and ShortflagsAll CLI commands should have a single-letter alias, and flags should have a long and short version. By default, the short version is the first letter of the long version. We may choose Response HeadersAll responses from the Nextercism API will provide:
TODO: these are tentative header values, we need to discuss/confirm. This will enable the CLI to update settings and prompt the user to upgrade the CLI. Authentication
Authentication happens via an HTTP request header. This header is sent on every request from the client. CommandsConfigure (shortname: c)
The configure command will call an API endpoint that provides values for all user-facing copy (confirmation messages, error messages, etc). It will also provide a list of API endpoints to use. Lastly it can take flags for user-provided values, as well as to override settings that are useful during development (e.g. the base API hostname). This will allow us to update the copy without releasing a new version of the CLI, as well as let us do A/B testing on copy based on flags in the database, and more easily deprecate old API endpoints or move the API should we need to. The CLI will ship with defaults (e.g. write default values to the config, which will then be overwritten after the first call is made). Download (shortname: d)
Users will no longer be able to download exercises that are not yet available to them on the site, however typically more than a few exercises will be available to them at once, so this should be a good experience. The API might return a 403, meaning that you can't access the exercise. The track can almost always be inferred based on context. Most people only work on one track. At other times we can determine the track based on the current location on the file system. If we are unable to disambiguate, we ask for confirmation. People can specify the If you download an exercise and there are already files there, we will either ask you if you want to overwrite the file (each file individually) or write them with a separate suffix. TODO: we need to decide whether to ask about overwriting, writing with a suffix. If you run the download command with You can download someone else's solution to something given a valid UUID.
This downloads it to a separate directory tree (TBD). E.g.
Submit (shortname: s)
Calling |
I love both of these things. They will remove some of the barrier and learning curve there is to the CLI. |
@ErikSchierboom Yeah, there have been some great ideas in this and earlier threads about simplifying. Another thing that we're going to do with the new one is ask for specific things interactively if they're not set. Ideally the new Exercism user will only need to know about |
@kytrinyx I'm still working my way through the discussion points to get a sense of what/why certain things are being proposed. But I do have some initial thoughts.
Great idea, this is great for informing about updates, depreciations, and general support.
I have some hesitation to downloading into a separate directory. The hesitations being: Has the option of downloading another users' solution alongside the users' implementation with a file name like |
I like this idea, but I'm wondering if there's any potential issues with tracks/solutions that contain multiple files? (e.g a solution whose entire directory was submitted) |
The most important concern for me right now is that you should be able to commit everything for a track to a git repository. Other people's solutions shouldn't go inside that. We would tell you where it got downloaded to so that you can change directory. The path that I'm thinking of using is |
I liked the SHA/UUID beeing part of the path in the current version, it allowed me to compare different iterations locally side by side. I think we should keep a way to distinguish different iterations after downloading them. |
How would you feel about numeric suffixes, so if you're looking at several iterations of Clock in Go by the user
|
Assuming that a user will be able to delete iterations as he is now, I do see some ambiguities in this approach:
I think there are more cases to consider which makes this a not-so-good-plan. I really do prefer to have the ID in the path. It also has the advantage that I can reconstruct a URL easily from the path (assuming that we will keep the currently used |
@NobbZ I need to think about this a bit more.
Do you prefer it for other things than reconstructing the URL? My plan for the
We will be keeping some hidden metadata in the exercise directory that will let the CLI reconstruct the exercise. My thinking with the sequential suffix on the directory was not to match the actual iteration number, but rather as a serial number indicating how many copies of the exercise you have locally. |
Using it just as a local counter, unrelated to the actual iteration does make sense for me. Also providing an option to open (or at least falling back to generating a link) from the CLI is a nice thing. |
I've opened issues for the nextercism reimplementation (https://github.com/exercism/cli/issues?q=is%3Aissue+is%3Aopen+label%3Anextercism) and I've started implementing the new client. The base branch for the new client is in exercism/cli#410, and I have a number of open pull requests to that branch https://github.com/exercism/cli/pulls?q=is%3Aopen+is%3Apr+label%3Anextercism |
Thanks, everyone, for helping hash this out! 🌻 |
I have been pondering rethinking the feature set for the client(s) for a while. The current feature set grew organically, and has some rough edges and surprising corners.
I think it would be interesting to take a step back and think through what the feature set should be, given what we now know about the app.
We have a number of open issues that are about tweaking the feature set:
exercism fetch <lang> --next
#72And another issue about feature parity:
And finally, we have some concerns that need to be taken into account:
What would be the consistent set of interactions?
/cc @exercism/cli-committers @holandes22
The text was updated successfully, but these errors were encountered: