learnersguild / echo-cli Goto Github PK

See Learner UX

@learner  > /log -r
@echo     > You have logged 0/12 of your reflections for this retrospective.
            Run `/log -r` at any time to check your progress.

            To log a reflection, pick a question using the command:
            `/log -r -q<integer from 1-12>`

            For example:
            `/log -r -q3` => show question 3 (of 12)

            Then follow the instructions specified in the question to answer.

[ 2 questions + reflections... ]

@learner  > /log -r
@echo     > You have logged 2/12 of your reflections for this retrospective.
            Run `/log -r` at any time to check your progress.

            To log a reflection, pick a question using the command:
            `/log -r<integer from 1-12>`

            For example:
            `/log -r -q3` => show question 3 (of 12)

            Then follow the instructions specified in the question to answer.

[ 10 more questions + reflections... ]

@learner  > /log -r
@echo     > Nice work! You've completed 100% of the reflections.

            To edit any of your reflections, just log it again before the end of the cycle.
@learner  > /log -r -q2 3
@echo     > Reflection for retrospective question 2 updated!

The retrospective form lives in a panel, opened by the /retro command (analogous to /vote).

If a player is only on one team/project, then the retro panel loads with the retrospective for that team/project.

If on multiple teams, then /retro requires a #project-id argument. Example:

-> /retro
=> Error: no project specified. Try `--help` for usage.
-> /retro --help
retro - log retrospectives

Usage:
    retro [options] [<project id>]

Options:
    --help, -h            print usage information
-> /retro #stable-snake   // => pops out retro panel for project

Related: LearnersGuild/rocketchat-lg-game#43

For example, with vote, if any positional parameters are passed, exactly two should be passed.

The initial version of this command (#27) was very minimal and was missing some of the features in the spec. We need to add the following:

• /review #project-id: display the user's current review for this project, with N/A as placeholders for missing completeness / quality values
• The response from submitting a review should contain the text Review is not yet complete. or Review is complete. Thank you for your input. as appropriate.

@jeffreywescott commented on Fri Jul 01 2016

Command descriptors can have an examples array, to show different usage examples.

E.g.

examples:
-
  example: log -r3
  description: Shows question 3 from retrospective.
-
  example: log -r1 ali:15 ben:15 cara:40 dwight:30
  description: Log reflection for question 1 (relative contribution).

Which will print out as:

Examples:
    Show question 3 from retrospective.
    > log -r3

    Log reflection for question 1 (relative contribution).
    > log -r1 ali:15 ben:15 cara:40 dwight:30

Errors generated by commands should not be public, but only visible to the user who issued the command. For example, if /cycle init throws an error, only show the error to the moderator.

I.e. don't clutter the channel with errors that other learners don't care about and can't resolve.

depends on game API implementation in LearnersGuild/echo#159

Completeness and quality are both percent scores between 0-100. Value passed can be a decimal, but will be rounded to the hundreds place after entering.

• /review #project-id --completeness 89 --quality 63.1: review both completeness and quality in one command
• /review #project-id -c28.2 -q63.1: review both completeness and quality, using short-form options
• /review #project-id --completeness 89: review just completeness
• /review #project-id -q 63.1: review just quality
• /review #project-id: display the user's current review for this project, with N/A as placeholders for missing completeness / quality values

Example Usage & Errors

@learner  > /review #silly-slug
@echo     > Project #silly-slug has 4 reviews. You have not reviewed project #silly-slug.

            To review this project, analyze their artifact:
            > http://link.to.artifact/

            Use the rubric provided to calculate and submit a `--completeness` and `--quality` score.
@learner  > /review #silly-slug --completeness 89
@echo     > Completeness score captured for #silly-slug! Review is not yet complete.
@learner  > /project list --in-review
@echo     > You have reviewed 2/5 projects this cycle. Nice work!

               Project                  C    Q    Artifact
            X  #terrible-tiger          63   42   https://github.com/owner/repo
            X  #anxious-aardvark        19   77   https://github.com/owner/repo
            -  #silly-slug              89        https://github.com/owner/repo
            -  #fantastic-falcon                  https://github.com/owner/repo
            -  #creepy-caterpillar                https://github.com/owner/repo
@learner  > /review --quality 103
@echo     > Error: missing project id.

            When reviewing a project, be sure to include its id (for example, #bitter-bunny-2).

            Use `/review --help` to read the docs.

@learner  > /review #silly-slug --quality 103
@echo     > Error: invalid quality score.

            Quality scores must be between 1 and 100 inclusive. Decimals up to the hundreds place are allowed.

            Use `/review --help` to read the docs.

@learner  > /review #silly-slug --quality 72
@echo     > Quality score captured for #silly-slug. Review is complete. Thank you for your input.
@learner  > /review #fantastic-falcon -c75.3 -q80.8
@echo     > Completeness and quality scores captured for #fantastic-falcon! Review is complete. Thank you for your input.

originated from LearnersGuild/learning-os-software#76

Things like:

• GraphQL parsing errors
• RethinkDB low-level errors

Right now, we get an index out of bounds exception with tons of RethinkDB garbage output that the user should never see.

Related: #28

/cc @tannerwelsh

There are some basic changes to make that can fix some low-hanging-fruit problems. After that, we need to pick one of two options: stick with the CLI and make it as good as possible, or build a GUI for the flex panel.

Basic Changes

Collapse teammate feedback questions into one

Instead of two separate questions/answers for teammate feedback, just use one:

Give feedback to your teammate by completing the following sentence:

"{{subject}}, I want to work with you because... and I would want to work with you more if..."

Improvement Option 1: Retro Form in Flex Panel

Switch to a GUI. Use similar flow to /vote.

• Disable /log command
• Make /retro command that opens retrospective panel
• Create paginated retrospective form template

Sketch mockup for form pages:

Improvement Option 2: Improved CLI

Use the same command structure but modify behavior to make UX less painful.

• With /log -r, don't show all questions. Only show progress and the next unanswered question.
• Provide a copy-pasteable example command with each question, so that learners run into fewer syntax errors.
• After answering a question, show the next unanswered question. This way learners don't need to issue a separate command to see the next question after answering one.
• Add guideline: avoid Echo responses that take up more than 1/3 of vertical screen. Having gigantic responses sucks, because it removes the visibility of history and thus context.

Set artifact for project: /project set-artifact #project-id <url>

Example Usage and Errors

@learner  > /project set-artifact https://github.com/owner/repo
@echo     > Error: invalid command - wrong number of arguments (1 for 2).

            Use `/project set-artifact --help` to read the docs.

@learner  > /project set-artifact #terrible-tiger https://github.com/owner/repo
@echo     > Thanks! The artifact for project #terrible-tiger is now set to https://github.com/owner/repo.

@jeffreywescott commented on Tue May 24 2016

Implement the /log command as outlined in the Learner UX document.

@jeffreywescott commented on Wed May 25 2016

This is probably blocked on #28

@jeffreywescott commented on Wed Jun 01 2016

See also: game-cli/#3

See also: LearnersGuild/echo#136

@jrob8577 commented on Fri Jul 01 2016

Expected vs. Actual

/review --help

Typo in Examples section: atrifact instead of artifact.

Steps to Reproduce

type /review --help in echo

Environment and Versions

What versions of relevant external software were you using (browser, OS, etc.)?

Use Cases

• /stats: show stats overview
• /stats STAT_NAME: show detail view for a particular stat
• /stats --help: print help on the stats command, including the list of available STAT_NAME arguments that will work.

• After being assigned to a project, I should be told what the project name is as well as the project's goal, goal number, and the team in the channel I'm currently in.
• The first message in a new project channels should mention and link to the goal.
• When joining a new project, I should see who else is on my team (or be told how to find them).

/cycle with no args prints a helpful help message, but /log just complains without telling me what my options are. The message it gives me is redundant as well.

@tannerwelsh what's the proper behavior? We should be consistent. (OND: I prefer the behavior of /cycle)

As a part of the retrospective, players should be determining the difficulty / stretchiness of the project.

Possible interface:

> /log -r -q7 1.2

Where the argument is the experienced difficulty, a float in the range -1..2 inclusive, corresponding to the following semantic markers:

-1: bored
0: comfortable
1: challenged (i.e. ZPD sweet spot)
2: overwhelmed

/review #project-id throws

*Error:* Invalid arguments. Try `--help` for usage.. Try `--help` for usage.

Instead it should summarize the review for the project.

This help doesn't show me that I can ask for help on a specific subcommand by typing, for example /project set-artifact --help

@bundacia commented on Thu Jun 30 2016

The test file for every command has a set of cut & pasted tests about how --help works and (in some cases) how to handle game service 500s. We should move these out into a shared namespace.

If the current cycle is not in GOAL_SELECTION state, then respond to /vote commands with the following message:

@echo > Voting is closed for the current cycle. When the moderator starts the next cycle, you will be able to vote on goals.

Players can list all of the projects for the current cycle, including information about whether or not they've reviewed by the player:

Command Examples

• /project list: list all projects for the current cycle
• /project list -r: list all projects for the current cycle that are currently in review
• /project list --in-review: list all projects for the current cycle that are currently in review (long form option)

Example Output

@learner  > /project list
@echo     > There are 5 projects active this cycle.
            You have completed 3 projects thus far. Your current project is in review.

            Run `/project list -r` to list projects in review.

@learner  > /project list --in-review
@echo     > You have reviewed 2/5 projects this cycle. Nice work!

               Project                  C    Q    Artifact
            X  #terrible-tiger          63   42   https://github.com/owner/repo
            X  #anxious-aardvark        19   77   https://github.com/owner/repo
            -  #silly-slug                        https://github.com/owner/repo
            -  #fantastic-falcon                  https://github.com/owner/repo
            -  #creepy-caterpillar                https://github.com/owner/repo

When logging a review score, there is no confirmation message. Because / commands are hidden after being issued, it's impossible to see what review scores were given.

Players can list all of the projects for the current cycle, including information about whether or not they've reviewed by the player:

Command Examples

• /project list -c: list all projects that have been completed by the current player
• /project list --completed: list all projects that have been completed by the current player (long form option)

Example Output

@learner  > /project list
@echo     > There are 5 projects active this cycle.
            You have completed 3 projects thus far. Your current project is in review.

            Run `/project list -r` to list projects in review.
            Run `/project list -c` to list projects you've completed.

@learner  > /project list --completed
@echo     > You have completed 3 projects.

            Project                  C    Q    Artifact
            #weary-worm              70   82   https://github.com/owner/repo
            #triumphant-toucan       83   67   https://github.com/owner/repo
            #barbaric-bear           90   72   https://github.com/owner/repo

Players can list all of the projects for the current cycle, including information about whether or not they've reviewed by the player:

Command Examples

• /project list: list all projects for the current cycle
• /project list -r: list all projects for the current cycle that are currently in review
• /project list --in-review: list all projects for the current cycle that are currently in review (long form option)

Example Output

@learner  > /project list
@echo     > There are 5 projects active this cycle.
            You have completed 3 projects thus far. Your current project is in review.

            Run `/project list -r` to list projects in review.

@learner  > /project list --in-review
@echo     > You have reviewed 2/5 projects this cycle. Nice work!

               Project                  C    Q    Artifact
            X  #terrible-tiger          63   42   https://github.com/owner/repo
            X  #anxious-aardvark        19   77   https://github.com/owner/repo
            -  #silly-slug                        https://github.com/owner/repo
            -  #fantastic-falcon                  https://github.com/owner/repo
            -  #creepy-caterpillar                https://github.com/owner/repo

Related: #27, #33

@prattsj commented on Fri Jul 01 2016

Expected vs. Actual

Expected:
Expected an error message indicating that the project could not be found / was invalid.

Actual:
Error:* Failed to save responses. Try--helpfor usage.

Steps to Reproduce

Submit a review that is valid in every way except for the project name:

/review misspelled-project -c 70 -q 70

Environment and Versions

Irrelevant.

We need to make sure that moderators can issue any moderator-relevant command (like vote sliding out the voting panel).

Previously, some of the commands depended on information from the player record (e.g., chapterId, goalRepositoryURL). However, now all of the checking for that is (rightfully) done on the game server and this dependency is no longer in place.

The only thing remaining-in-use by game-cli from the lgPlayer attribute is the id (to ensure that the user is a player, which we can just as easily do with lgUser.roles). This commit removes any dependency that game-cli has on an lgPlayer being passed-in.

This is a prerequisite for:

• LearnersGuild/rocketchat-lg-sso#31
• LearnersGuild/rocketchat-lg-sso#32

Based on LearnersGuild/echo#136, the command should be /cycle reflect not /cycle retro.

With separate /retro and /review commands, this is no longer needed.

Holding future tensions about this change.

Right now, there are places all over the code that are checking to see if the given user has a certain role. This is wrong -- instead, we should be checking whether or not the user has a given capability. Ideally, this would just be done by the game service itself, and the CLI would just trust the game service to reject the API calls with a correct response.

Tension 1

It seems awkward that the -r option is used both to request the printing of all questions if no number is given and also to specify a specific question.

Tension 2

The full version of -r is --reflection, but it's actually naming the index of a specific reflection in the context of the retrospective survey. The name seems wrong.

Proposal (OND):

# print out the full retrospective survey
/log --retro 

# print out question 4 from the retrospective survey
/log --retro -n4

# answer question 4 from the retrospective survey
/log --retro -n4 "my answer!"

https://github.com/LearnersGuild/game-cli/blob/master/config/commands/log.yaml

@shereefb commented on Tue Jul 05 2016

If I want to update my numbers, I can just re-submit the command. It would be great to have this clarified in the documentation of the command.

@prattsj commented on Fri Jun 24 2016

Following a /cycle init attempt in echo-chat:

Errors show the "Try --help for usage." message twice. They only need to display that message once.

This is needed to provide consistent, "Unix-like" command-line argument and option parsing. It will be used (immediately) by rocketchat-lg-slash-commands, but also will likely be used in the future to provide a terminal-based set of commands that players can use without having to switch contexts into chat.

See also: rocketchat-lg-slash-commands/#27

From @bundacia's comment #76 (comment):

My suggestions (ONA) would be to:

A) Have /project list list projects by default, either those the player is currently working on, or all of the active projects in the chapter.

and/or

B) Change the -r flag to be short for --reviews or something more accurate instead of --in-review

See: LearnersGuild/los#9