🌺 Quality of life improvements #49

erunion · 2019-07-20T08:38:11Z

rdme as it exists has a horde of usability issues:

No commands are documented.
There's no way to get help for individual commands (and they aren't documented anyway).
Error handling is all over the place. Sometimes we return nice, colored, errors, others we dump raw JSON responses to the console.

There's got to be a better way!

Improvements

All commands have been fully documented.
More command categories/groups have been created: "Administration", "Sync Swagger/OpenAPI files", "Documentation", and "Versions"
Heavily improved error handling to account for the wide variety of error cases that might happen (API errors, type errors, bad command argument errors, unexpected errors, etc.)
Cleaned up a lot of the errors that we were returning so they're more consistently represented.
🆕 Added support for getting help via rdme <command> --help and rdme help <command>
🆕 Related commands are now surfaced on command help screens. So for example if you do rdme help versions, you'll see a related commands list of every other versions-related command available.
🆕 Owlbert has been added to the main rdme help screen because everyone needs more Owlbert.

In action

$ ./rdme.js

          ░                                        ░
          ░░                                       ░░
        ░░░░░                                     ░░░░ ░
       ░░░░░░░                                    ░░░░░░
       ▐░░░░░░▄                                 ░░░░░░░░░
       ░░░░░░░░░▐░░░                        ░░░░░░░░░░░░░   rdme
        ░░░░░░░░░░░░░░░░░▐▐▐░░░░░░░░░░▐▐░░░░░░░░░░░░░░░░░░
      ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    a utlity for interacting with ReadMe.io
      ▐░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
      ▐░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
      ▐░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▄▄▄▄░░░
      ▐░░░░░░░░░░░░░░░▄█▓▓▓▓▓▓█▄░░░░░░░░░░░░░░▄█▓▓▓▓▓▓▓▓▓▄░          ░░
      ▐░░░░░░░░░░░░▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄░░░░░░░░░▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄       ░░░░░░░░░
      ░░░░░░░░░░░░▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▌░░░░░░░▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄      ░░░░░░░░░░
      ░░░░░░░░░░░▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄░░░░░░▒▓▓▓▓█▀▓▓▓▓▓▓▓▓▓▓▓    ░░░░░░░░░░░░░░░░
      ░░░░░░░░░░░▒▓▓▓▓▀  ▓▓▓▓▓▓▓▓▓▓▓▌░░░░░░▐▓▓▓   ▀▀▓▓▓▓▓▓▓▓▌   ░░░░░░░░░░░░░░░░
      ▐░░░░░░░░░░▐▓▓▓▌     ▐▓▓▓▓▓▓▓▓░░░░░░░░▀▓▓▄   ▄▓▓▓▓▓▓▓▓   ░░░░░░░░░░░░░░░░
      ▐░░░░░░░░░░░▐▓▓▓▌▄ ▄▄▓▓▓▓▓▓▓▓▀░░░░░░░░░░▀▓▓▓▓▓▓▓▓▓▓█▀  ░░░░░░░░░░░░░░░░
      ▐░░░░░░░░░░░░░▀▓▓▓▓▓▓▓▓▓▓▓█▀░░░░░░░░░░░░░░░▀▀▀▀▀▀░░░  ░░░░░░░░░░░░░░░
      ▐░░░░░░░░░░░░░░░░▀▀▀▀▀▀▀░░░░░░░░░░▄▄▄░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
      ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒▒▒▒▒▒▒░░░░░░░░░░░░░░░░░░░░░░░░░
     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▀▒▒▒░░░░░░░░░░░░░░░░░░░░░░░░
    ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▀░░░░░░░░░░░░░░░░░░░░░
   ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Usage: rdme <command> [arguments]

Available commands

  Administration
    $ rdme login             Login to a ReadMe project. 

  Sync Swagger/OpenAPI files
    $ rdme swagger           Upload, or sync, your Swagger/OpenAPI file to ReadMe. 

  Documentation
    $ rdme docs              Sync a folder of markdown files to your ReadMe project.         
    $ rdme docs:edit         Edit a single file from your ReadMe project without saving      
                             locally.                                                        

  Versions
    $ rdme versions          List versions available in your project or get a version by     
                             SemVer (https://semver.org/).                                   
    $ rdme versions:create   Create a new version for your project.                          
    $ rdme versions:delete   Delete a version associated with your ReadMe project.           
    $ rdme versions:update   Update an existing version for your project.                    

  Other useful commands
    $ rdme open              Open your current ReadMe project in the browser.                
    $ rdme oas               OAS related tasks. See https://npm.im/oas for more information. 

Options

  -h, --help       Display this usage guide      
  -v, --version    Show the current rdme version 

Run rdme help <command> for help with a specific command.

$ ./rdme.js help versions

List versions available in your project or get a version by SemVer (https://semver.org/).

Usage

  rdme versions [options] 

Options

  --key string       Project API key          
  --version string   Project version          
  -h, --help         Display this usage guide 

Related commands

  $ rdme versions:create   Create a new version for your project.                
  $ rdme versions:delete   Delete a version associated with your ReadMe project. 
  $ rdme versions:update   Update an existing version for your project.

erunion · 2019-07-23T17:11:46Z

@gratcliff You should take a look at this to make sure I didn't lose anything you added in the versions additions.

gratcliff · 2019-07-23T17:12:47Z

@gratcliff You should take a look at this to make sure I didn't lose anything you added in the versions additions.

Absolutely! In the processes of looking as we speak. Some of that fs work is top notch!

lib/help.js

amyshi188 · 2019-07-24T20:13:41Z

I noticed when importing a spec file with the CLI tool that the command is different:

It doesn't indicate that the Swagger file needs to come after "swagger" which might be confusing to new users. It would be clearer if it looked something like this: rdme swagger {path-to-swagger.json} --key={api-key}, which we show on https://www.npmjs.com/package/rdme.

I don't know what the reason was for changing it but maybe this is something to consider?

erunion · 2019-07-25T16:56:20Z

@amyshi188 How about this instead:

$ ./rdme.js help swagger

Upload, or sync, your Swagger/OpenAPI file to ReadMe.

Usage

  rdme swagger [path-to-spec.json] 

Options

  --key string       Project API key                                                               
  --id string        Unique identifier for your specification. Use this if you're resyncing an     
                     existing specification                                                        
  --version string   Project version                                                               
  -h, --help         Display this usage guide

I kind of want to keep --key off the usage line for it because it's technically not required because if you've used rdme login we save your key and re-use that.

mjcuva · 2019-07-25T22:39:43Z

@amyshi188 We actually changed it so you don't need the path to the file anymore! If you don't provide one it will automatically try to find one, and if it can't then we ask the user to enter the path. So for new users it's probably better to not include the path at all!

erunion · 2019-07-25T22:41:52Z

I'm good to keep the usage for the swagger command as rdme swagger [spec] since it'll be nice to know when looking for help on that command to see that it does take a spec as an argument even though it's optional.

I talked offline with @gratcliff and I've accidentally removed a heap of argument support on the new versions commands, so I'm working on resurrecting those.

erunion · 2019-07-26T19:28:20Z

@gratcliff @mjcuva Pushed up a handful of fixes for the versions commands that I broke, as well as updating rdme versions to return its data within a table:

$ ./rdme.js versions
┌─────────┬──────────┬───────────────┬───────────┬─────────┬───────────┬──────────────────────────┐
│ Version │ Codename │ Is deprecated │ Is hidden │ Is beta │ Is stable │ Created on               │
├─────────┼──────────┼───────────────┼───────────┼─────────┼───────────┼──────────────────────────┤
│ 1.0     │          │ yes           │ yes       │ yes     │ no        │ 2019-06-17T22:39:56.462Z │
└─────────┴──────────┴───────────────┴───────────┴─────────┴───────────┴──────────────────────────┘

gratcliff · 2019-07-29T21:10:57Z

@gratcliff @mjcuva Pushed up a handful of fixes for the versions commands that I broke, as well as updating rdme versions to return its data within a table:

$ ./rdme.js versions
┌─────────┬──────────┬───────────────┬───────────┬─────────┬───────────┬──────────────────────────┐
│ Version │ Codename │ Is deprecated │ Is hidden │ Is beta │ Is stable │ Created on               │
├─────────┼──────────┼───────────────┼───────────┼─────────┼───────────┼──────────────────────────┤
│ 1.0     │          │ yes           │ yes       │ yes     │ no        │ 2019-06-17T22:39:56.462Z │
└─────────┴──────────┴───────────────┴───────────┴─────────┴───────────┴──────────────────────────┘

I agree with you that the table is cleaner, but it's pruning some key information in regards to pulling specific versions:

gratcliff

Looks great overall. Clean code is previously mentioned. In regards to version outputs, it may be beneficial to dump JSON. Either A) for mocking or B) to pipe into a bash script for programmatic usage. Otherwise, there should be differing information between rdme versions and rdme versions --version=VERSION (select v entire object dump, respectively). If you'd like to keep the table, maybe it makes sense to add a pretty flag?

erunion · 2019-07-29T21:55:48Z

@gratcliff That's fair, but I was thinking that since this is a CLI wrapper around the API, that everything should be "pretty" by default. Maybe we can add a raw option to the versions command that'll dump the raw API output instead?

I'll go back and work in the missing data for the single version that I'm not currently surfacing in the prettified version though.

gratcliff · 2019-07-29T21:56:54Z

@gratcliff That's fair, but I was thinking that since this is a CLI wrapper around the API, that everything should be "pretty" by default. Maybe we can add a raw option to the versions command that'll dump the raw API output instead?

I'll go back and work in the missing data for the single version that I'm not currently surfacing in the prettified version though.

Works for me! If we do can you update the README.md to reflect that?

erunion · 2019-07-30T21:00:39Z

@gratcliff Took another pass on versions and it's ready for your review again.

Version: 1.0
Codename: None
Created on: 2019-06-17T22:39:56.462Z
Released on: 2019-06-17T22:39:56.462Z
┌───────────────┬───────────┬─────────┬───────────┐
│ Is deprecated │ Is hidden │ Is beta │ Is stable │
├───────────────┼───────────┼─────────┼───────────┤
│ yes           │ yes       │ yes     │ no        │
└───────────────┴───────────┴─────────┴───────────┘

Since we don't have an API endpoint to pull information from categories, I'm opting (for now) to not expose that in the "pretty" format, but I did add a --raw option to just dump the API output to the terminal instead.

lib/help.js

gratcliff

Jon this looks fantastic! Minor request below

README.md

erunion added 3 commits July 19, 2019 14:37

Cleaning up --help.

e30935b

Adding Owlbert to --help

931e14e

Constructing a help engine for subcommands.

3d28b0f

erunion added the enhancement New feature or request label Jul 20, 2019

erunion added 10 commits July 20, 2019 01:58

Migrating the oas command into the new framework.

2012d38

Migrating the open command over and pouring some sugar on it.

6e21154

Migrating the login command over.

242e62c

Migrating the docs commands over.

3e0b8cb

Migrating the version commands over.

a1e8e34

Fixing broken command unit tests.

7199c2a

Running Prettier on everything.

494c713

Fixing broken unit tests.

e088aea

Boosting code coverage.

45d1955

Adding support for rdme help <command>.

c568791

erunion changed the title ~~Quality of life improvements~~ 🌺 Quality of life improvements Jul 22, 2019

erunion added 2 commits July 22, 2019 17:08

Cleaning up the main help screen.

4cafbc3

Surfacing related commands on command help screens.

325eb8c

erunion marked this pull request as ready for review July 23, 2019 00:53

erunion requested review from mjcuva, gratcliff, dok, kanadgupta, gkoberger and rafegoldberg July 23, 2019 00:53

Fixing some typos in code comments.

90b473a

kanadgupta reviewed Jul 24, 2019

View reviewed changes

lib/help.js Outdated Show resolved Hide resolved

Preferring readme.com over readme.io

74425c3

erunion added 6 commits July 25, 2019 16:23

Re-adding supported arguments to the versions commands.

c4cde32

Fixing broken unit tests.

ef8fd5e

Using a better table library for rdme versions.

ee0f349

Running prettier on everything.

9dac2c0

Fixing a broken versions command test.

5dcfdc3

Expanding our builds to run on Node 12

6d3b0dc

gratcliff requested changes Jul 29, 2019

View reviewed changes

Reformatting the output of the versions command to show more data.

b0bd08f

Running Prettier on everything.

dbc27b0

rafegoldberg reviewed Aug 1, 2019

View reviewed changes

lib/help.js Show resolved Hide resolved

Aligning the tagline with the program name.

f810a48

gratcliff self-requested a review August 2, 2019 21:31

gratcliff reviewed Aug 2, 2019

View reviewed changes

README.md Show resolved Hide resolved

erunion added 4 commits August 2, 2019 15:55

Cleaning up the README file.

18dca78

Removing a couple more duplicate --key arguments in the readme.

7ab97c5

A few more readme tweaks.

7d764b3

Fixing a typo in the readme.

84f819d

gratcliff self-requested a review August 2, 2019 22:59

gratcliff approved these changes Aug 2, 2019

View reviewed changes

erunion merged commit 5213eba into master Aug 2, 2019

erunion deleted the feature/qol-improvements branch August 2, 2019 23:03

erunion mentioned this pull request Aug 3, 2019

Adding new authentication oriented commands #53

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🌺 Quality of life improvements #49

🌺 Quality of life improvements #49

erunion commented Jul 20, 2019 •

edited by rafegoldberg

Loading

erunion commented Jul 23, 2019

gratcliff commented Jul 23, 2019

amyshi188 commented Jul 24, 2019 •

edited

Loading

erunion commented Jul 25, 2019

mjcuva commented Jul 25, 2019 •

edited

Loading

erunion commented Jul 25, 2019

erunion commented Jul 26, 2019

gratcliff commented Jul 29, 2019

gratcliff left a comment

erunion commented Jul 29, 2019

gratcliff commented Jul 29, 2019

erunion commented Jul 30, 2019

gratcliff left a comment •

edited

Loading

🌺 Quality of life improvements #49

🌺 Quality of life improvements #49

Conversation

erunion commented Jul 20, 2019 • edited by rafegoldberg Loading

Improvements

In action

erunion commented Jul 23, 2019

gratcliff commented Jul 23, 2019

amyshi188 commented Jul 24, 2019 • edited Loading

erunion commented Jul 25, 2019

mjcuva commented Jul 25, 2019 • edited Loading

erunion commented Jul 25, 2019

erunion commented Jul 26, 2019

gratcliff commented Jul 29, 2019

gratcliff left a comment

Choose a reason for hiding this comment

erunion commented Jul 29, 2019

gratcliff commented Jul 29, 2019

erunion commented Jul 30, 2019

gratcliff left a comment • edited Loading

Choose a reason for hiding this comment

erunion commented Jul 20, 2019 •

edited by rafegoldberg

Loading

amyshi188 commented Jul 24, 2019 •

edited

Loading

mjcuva commented Jul 25, 2019 •

edited

Loading

gratcliff left a comment •

edited

Loading