dvc: update cmd output strings to match docs by jorgeorpinel · Pull Request #3471 · treeverse/dvc

jorgeorpinel · 2020-03-11T16:31:55Z

to match treeverse/dvc.org/pull/1014
and now treeverse/dvc.org/pull/1040 too

❗ Have you followed the guidelines in the Contributing to DVC list?
📖 Check this box if this PR does not require documentation updates, or if it does and you have created a separate PR in dvc.org with such updates (or at least opened an issue about it in that repo). Please link below to your PR (or issue) in the dvc.org repo.
❌ Have you checked DeepSource, CodeClimate, and other sanity checks below? We consider their findings recommendatory and don't expect everything to be addressed. Please review them carefully and fix those that actually improve code or fix bugs.

Thank you for the contribution - we'll try to review it as soon as possible. 🙏

per treeverse/dvc.org@2c34521

shcheklein · 2020-03-11T16:40:12Z

    metrics_add_parser.set_defaults(func=CmdMetricsAdd)

-    METRICS_MODIFY_HELP = "Modify metric file options."
+    METRICS_MODIFY_HELP = "Modify metric file values."


it should be options.

modifying values sounds like we actually modify metric values.

it is about setting up metric file settings (type, path, etc), not modifying metric values

I see. I'll update this... ⏳ but still need the PR for other strings.

What about "default formatting"? See latest version here and in treeverse/dvc.org/pull/1014

default formatting options is still better? )

I'm trying to avoid term "option" here since there are also command options (CLI flags) and config options (DVC settings) and it gets confusing some times in the explanations.

Yep, I got the idea. I think it's almost impossible to avoid unfortunately in general (even if it works in this case). At least I was not able to find a good solution - may be even primarily I never thought that it's a really big deal - usually it's clear from the context. And can add more words when it's not clear from the context I think.

I think I managed to avoid the term everywhere actually 🙂 assuming we let this one through. Yes it's not always a big deal but in this case and others I changed I thought it was confusing since all the "option" concepts are used in the same doc or even section of the doc sometimes.

using term "formatting" instead of "options"

…ptions" per treeverse/dvc#3471 (review)

That's treeverse/dvc.org/pull/1014

It's a public fn after all. Similar to Repo class

efiop · 2020-03-18T19:23:44Z


    # Pull
-    PULL_HELP = "Pull data files from a DVC remote storage."
+    PULL_HELP = "Download tracked files or directories from remote storage."


Not sure pull and fetch help messages are different enough now. But it is definitely not worse.

Good point. I'm just copying from https://dvc.org/doc/command-reference/fetch and https://dvc.org/doc/command-reference/pull here. This whole PR is about matching docs which I think is desirable but if not, please lmk!

efiop · 2020-03-18T19:24:22Z

    list_parser.add_argument(
-        "url",
-        help="Supported urls:\n"
-        "/path/to/file\n"


Not sure why are we getting rid of these useful examples. In favor of docs?

Yeah for consistency with get and import and so the output here is shorter. We could go the opposite way and list all the examples in all these commands if that's preferable. Or we could add a link to the cmd ref in each one. Please lmk, happy to change it.

efiop · 2020-03-18T19:27:21Z

    metrics_modify_parser.set_defaults(func=CmdMetricsModify)

-    METRICS_REMOVE_HELP = "Remove files's metric tag."
+    METRICS_REMOVE_HELP = "Stop tracking a metric file."


This might be confusing. We are not stopping tracking the file but rather un-marking it as a metric.

True. I'm updating this one and metrics add, as well as the cmd refs. See f262f48 and treeverse/dvc.org/pull/1072. Thanks!

efiop · 2020-03-18T19:28:17Z

    pipeline_show_parser.set_defaults(func=CmdPipelineShow)

-    PIPELINE_LIST_HELP = "List pipelines."
+    PIPELINE_LIST_HELP = "List connected groups of stages (pipelines)."


Why are we making this clarification here, but not in other places? pipeline is self descriptive enough, I don't think it needs a "connected groups of stages"

Good question. Again, this is to match docs, https://dvc.org/doc/command-reference/pipeline/list specifically.

but not in other places

The only other place really is pipeline show which reads "Show stages in a pipeline." This one also mentions both terms "stage" and "pipeline" so it's similarly clear, I think.

efiop · 2020-03-18T19:29:08Z

    fix_subparsers(remote_subparsers)

-    REMOTE_ADD_HELP = "Add remote."
+    REMOTE_ADD_HELP = "Add a new data remote."


Are we sure we need data here? Won't it be confusing in regards to models and such?

Sorry to repeat the same answer haha but just matching docs here (https://dvc.org/doc/command-reference/remote/add).

For consistency, we use the term "data remote" in remote subcommands cmd refs (not in other docs though). This is kind of arbitrary, I agree on that. Would you prefer a different standard? Happy to update everywhere.

efiop · 2020-03-18T19:29:48Z


 def add_parser(subparsers, parent_parser):
-    REMOVE_HELP = "Remove DVC-file outputs."
+    REMOVE_HELP = "Remove data files or directories tracked by DVC."


This is not only about data, but about stages/models/etc too.

Hmmm OK changed to "Remove DVC-tracked files or directories." both here and in the cmd ref now. Better? The part about removing entire stage files is explained in the cmd ref desc.

efiop · 2020-03-18T19:30:21Z

 def add_parser(subparsers, parent_parser):
-    REPRO_HELP = "Check for changes and reproduce stages and dependencies."
+    REPRO_HELP = "Reproduce complete or partial pipelines"
+    " by executing their stages."


maybe running?

Since we have dvc run command, we use the term "execute" a lot in the repro cmd ref (https://dvc.org/doc/command-reference/repro).

efiop · 2020-03-18T19:32:35Z

Sorry for the delay.

per #3471 (review)

per treeverse/dvc#3471 (review)

per #3471 (review)

per treeverse/dvc#3471 (review)

per #3471 (review)

per treeverse/dvc#3471 (review)

efiop · 2020-03-23T15:41:21Z

Ok, merging for now. Will try to keep an eye on the docs PRs.

jorgeorpinel added 3 commits February 28, 2020 00:49

metrics show: update -h output to match docs

8b2dca0

per treeverse/dvc.org@2c34521

Merge branch 'master' of github.com:iterative/dvc

e82952a

metric: update argument desc per treeverse/dvc.org/pull/1014

fb139ff

jorgeorpinel mentioned this pull request Mar 11, 2020

Regular updates (late Feb) treeverse/dvc.org#1014

Merged

shcheklein reviewed Mar 11, 2020

View reviewed changes

metrics: match treeverse/dvc.org/pull/1014 again...

5c4f4ad

using term "formatting" instead of "options"

jorgeorpinel added a commit to treeverse/dvc.org that referenced this pull request Mar 11, 2020

api ref: update metrics docs to use phrase "formatting" instead of "o…

e96b22e

…ptions" per treeverse/dvc#3471 (review)

jorgeorpinel added 2 commits March 11, 2020 18:28

list: update help output to match treeverse/dvc.org/pull/1014

e3c087e

That's treeverse/dvc.org/pull/1014

dvc: add docstring to open_by_relpath

1a970c6

It's a public fn after all. Similar to Repo class

jorgeorpinel changed the title ~~metrics: update output strings to match iterative/dvc.org/pull/1014~~ metrics: update output strings to match docs Mar 12, 2020

jorgeorpinel commented Mar 12, 2020

View reviewed changes

Comment thread dvc/command/ls.py Outdated

jorgeorpinel commented Mar 12, 2020

View reviewed changes

Comment thread dvc/external_repo.py Outdated

jorgeorpinel requested a review from efiop March 12, 2020 00:33

help: update cmd output strings to match with docs

f5cda0d

jorgeorpinel changed the title ~~metrics: update output strings to match docs~~ commands: update output strings to match docs Mar 12, 2020

Merge branch 'master' into 2020-02-21

6526c09

efiop reviewed Mar 18, 2020

View reviewed changes

Comment thread dvc/command/metrics.py

efiop reviewed Mar 18, 2020

View reviewed changes

Comment thread dvc/command/root.py Outdated

jorgeorpinel added 2 commits March 18, 2020 23:01

remote: update help output

d5f2ffe

term: file descriptor -> file object

f262f48

jorgeorpinel changed the title ~~commands: update output strings to match docs~~ dvc: update cmd output strings to match docs Mar 19, 2020

metrics: update add and remove help outputs

47090e7

per #3471 (review)

jorgeorpinel added a commit to treeverse/dvc.org that referenced this pull request Mar 19, 2020

api ref: update metrics add and remove descs

821359c

per treeverse/dvc#3471 (review)

jorgeorpinel mentioned this pull request Mar 19, 2020

Regular updates (March 18) treeverse/dvc.org#1072

Merged

remove: update help output

3776104

per #3471 (review)

jorgeorpinel added a commit to treeverse/dvc.org that referenced this pull request Mar 19, 2020

cmd ref: update remvoe desc.

415901f

per treeverse/dvc#3471 (review)

root: update help output

b6f9cc1

per #3471 (review)

jorgeorpinel added a commit to treeverse/dvc.org that referenced this pull request Mar 19, 2020

cmd ref: update root definition

5fc3884

per treeverse/dvc#3471 (review)

Merge branch 'master' into 2020-02-21

1074e21

jorgeorpinel requested a review from efiop March 19, 2020 06:54

efiop merged commit 9e77405 into treeverse:master Mar 23, 2020

jorgeorpinel deleted the 2020-02-21 branch October 12, 2020 00:18

Conversation

jorgeorpinel commented Mar 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

jorgeorpinel Mar 11, 2020 • 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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

efiop Mar 18, 2020 • 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!

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!

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!

efiop commented Mar 18, 2020

Uh oh!

efiop commented Mar 23, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jorgeorpinel commented Mar 11, 2020 •

edited

Loading

jorgeorpinel Mar 11, 2020 •

edited

Loading

efiop Mar 18, 2020 •

edited

Loading