UI suggestions

[dberenbaum]

UI suggestions for the output of gto show:

$ gto show
╒══════════╤═══════════╤═════════════════╤════════════════════╕
│ name     │ version   │ stage/staging   │ stage/production   │
╞══════════╪═══════════╪═════════════════╪════════════════════╡
│ features │ -         │ -               │ -                  │
│ foo      │ -         │ -               │ -                  │
│ nn       │ v0.0.1    │ v0.0.1          │ -                  │
│ rf       │ v1.0.1    │ -               │ v1.0.1             │
╘══════════╧═══════════╧═════════════════╧════════════════════╛

1. What is version? Is it the latest version? If so, what about latest?
2. This isn't specific to gto show, but consider making the default output format grep-able, like:

$ gto show
name        version stage/staging   stage/production
features    -       -               -
foo         -       -               -
nn          v0.0.1  v0.0.1          -
rf          v1.0.1  -               v1.0.1

[dberenbaum]

For gto audit, I would again suggest to make it more grep-able, combining the output into a single table as suggested in https://devcenter.heroku.com/articles/cli-style-guide#grep-parseable.

[aguschin]

Thanks for feedback! Actually, you can get this:

$ gto show -r pytest-cache/test_api0 -ft plain

Probably, there should be less options so this one would easier to be found. Or it should in gto show --help docs, in examples section. Do you think the last option would resolve the issue?

[dberenbaum]

Yes, gto show -ft plain looks good to me. For DVC, we decided that we would use that style as the default. See iterative/dvc#6046 and https://clig.dev/#output ("Have machine-readable output where it does not impact usability"). We should consider whether to adopt a standard across our products for consistency.

cc @shcheklein

[dberenbaum]

Also, regarding the -ft flag, I would suggest that we could pick a single table format. If we need to provide support for other table formats like tsv or some fancier format, we can probably just append those options to the -f flag instead of have two separate formatting flags.

[dberenbaum]

@shcheklein Any thoughts on where we could document clig.dev and other guidelines for CLI?

[shcheklein]

@dberenbaum here https://www.notion.so/iterative/Making-CLI-apps-in-Python-e4fcdeaf6b564986b0973cf0e095dc3d ?

A few comments:

• -ft (and if we have some other option names like this). There is a convention to consider this as -f -t (e.g. set -uex). I would avoid this. -f, --format is better.

• --plain, --terse, --jsonetc vs --format something style. I would check what we use in DVC and the other tools. I know that in DVC we--json, --md`:

Terse, machine-readable output formats can also be useful but shouldn’t get in the way of making beautiful CLI output. When needed, commands should offer a --json and/or a --terse flag when valuable to allow users to easily parse and script the CLI.

one of the examples, I would check with @skshetry if there is an exact agreement on this.

@dberenbaum do we have other examples, something similar to -f something

• +1 on trying to keep "plain" by default

[dberenbaum]

--plain, --terse, --jsonetc vs --format something style.

This has been brought up for dvc exp show (see iterative/dvc#6933 (comment)), but there's been no consensus. For now, dvc has not used --format and has instead used separate flags like --json, --csv, etc., which should be grouped together in help text in a mutually exclusive group.

[aguschin]

Thanks for all the feedback. One more question. Should there be an option to output names only? E.g.

$ gto show --names-only
features
foo
nn
rf

If yes, what the option name should be?

[dberenbaum]

Both dvc stage list and dvc exp list have --names-only arguments, so that looks good to me.

[skshetry]

Now I think of it, it should probably be --name-only instead of --names-only, to mean that it affects individual entries to only return a name rather than the whole list.

See git diff --name-only

[dberenbaum]

If we go with --name-only, let's make an issue in dvc to change/alias the option name there.

[aguschin]

Thanks everyone for the great feedback!

What I've done in #118 :

1. Added --name-only for GTO.
2. Added --json and --plain. I believe having nicely formatted table in gto show makes it much easier to read, so by default I've kept that formatting.

So, now there are three mutually exclusive options

  --json              Print output in json format
  --plain             Print table in grep-able format
  --name-only         Print names only

Output looks like this:

$ gto show
╒════════╤═══════════╤════════════════════╤═════════════════╕
│ name   │ version   │ stage/production   │ stage/staging   │
╞════════╪═══════════╪════════════════════╪═════════════════╡
│ nn     │ v0.0.1    │ -                  │ v0.0.1          │
│ rf     │ v1.2.4    │ v1.2.4             │ -               │
╘════════╧═══════════╧════════════════════╧═════════════════╛

$ gto show --plain
name    version    stage/staging    stage/production
nn      v0.0.1     v0.0.1           -
rf      v1.2.4     -                v1.2.4

$ gto show --json
{
    "nn": {
        "version": "v0.0.1",
        "stage": {
            "staging": "v0.0.1",
            "production": null
        }
    },
    "rf": {
        "version": "v1.2.4",
        "stage": {
            "staging": null,
            "production": "v1.2.4"
        }
    }
}

$ gto show --name-only
nn
rf

[aguschin]

Please post any feedback if you have it, otherwise I'm closing the issue :)

[dberenbaum]

Looks good, thanks @aguschin.

1. What is version? Is it the latest version? If so, what about latest?

Thoughts on this? Should we put in a different issue?

[aguschin]

Thanks, @dberenbaum!
Yep, it's the latest version. I guess we need to rename it to "latest version" then:

$ gto show
╒══════════╤═════════════════╤═════════════════╤════════════════════╕
│ name     │ latest version  │ stage/staging   │ stage/production   │
╞══════════╪═════════════════╪═════════════════╪════════════════════╡
│ features │ -               │ -               │ -                  │
│ foo      │ -               │ -               │ -                  │
│ nn       │ v0.0.1          │ v0.0.1          │ -                  │
│ rf       │ v1.0.1          │ -               │ v1.0.1             │
╘══════════╧═════════════════╧═════════════════╧════════════════════╛

[aguschin]

I have one more question about this "latest version" column TBH.
Let's suppose

1. I have two commits: c1 and c2.
2. I register model in c1 (create git tag [email protected]). Now it's latest:

$ gto show
╒══════════╤═════════════════╕
│ name     │ latest version  │
╞══════════╪═════════════════╡
│ features │ v1.0.0          │
╘══════════╧═════════════════╛

3. I promote model in c2 (create git tag model#prod). Now obviously, this could be perceived as latest - because I created the 2nd git tag later the 1st, even though it isn't explicitly registered SemVer version.

Should gto show print c2 hexsha as "latest version" with some flag? E.g. this:

$ gto show --include-promoted-versions
╒══════════╤═════════════════╕
│ name     │ latest version  │
╞══════════╪═════════════════╡
│ features │ c1-hexhsa       │
╘══════════╧═════════════════╛

Or should it be default behavior?

Also consider the case when I don't register versions at all, just making promotions. Then "latest version" column should contain this commit hexsha by default?

The same question for gto latest cmd.

[dberenbaum]

IMO we should restrict that column to semver tags and ignore any commit hexshas, even if they are used in promotion. The commit hexsha is already visible in the stage columns. I don't see much utility in adding this flag for now. If someone needs it, you can always add it later.