cmd-ref: document data:status command

[skshetry]

I have tried to keep it simple.

I was not sure what to add in data/index.md, so I started to introduce a few concepts around index/dvc-data, which is going to be helpful in the data/status.md to clarify and not repeat that we are comparing to file hashes in dvc.lock and .dvc files and just mention the term index. But I did not go completely and introduce that concept yet. :)

Closes #3732.

[github-actions[bot]]

Link Check Report

There were no links to check!

[dberenbaum]

Looks good!

A couple high-level comments:

1. Could some of the introductory text be more generic ("Show changes/status of data tracked by DVC") instead of immediately jumping into all of the "indexes" being compared? While that detail is important, to me it seems like it's too much of the focus here and is introduced too early and repeated too much. It makes it hard to get an overview of the command.
2. Would it be useful to directly compare to git status? I think that a helpful way to frame this command and show how it might be useful over the existing dvc status is to make the analogy to git status and maybe even suggest using them together or show that in the examples as a way to get a holistic status of the repo.

[dberenbaum]

@skshetry When you are available, could you do another iteration on this?

[dberenbaum]

@skshetry What's the status of this one? Do you need someone else to take over?

[skshetry]

@skshetry What's the status of this one? Do you need someone else to take over?

@dberenbaum, I have been prioritizing the bugfix for https://github.com/iterative/dvc/issues/8052 over this. The major issue here is about how to describe this command: https://github.com/iterative/dvc.org/pull/3812#discussion_r930458955, other seems minor.

[dberenbaum]

Let's try to get this merged this sprint. I think with 1-2 more iterations, we should be able to merge something and follow up later if needed.

~@skshetry When do you expect to have another iteration ready? I can also take over if needed.~

Edit: I missed your most recent responses and that I posted a similar comment a couple days ago 🤦 .

[dberenbaum]

@skshetry I'll plan to merge once you address those comments. Thanks everyone for your help here!

[skshetry]

I’ll remove index and push another version tomorrow. :)

[skshetry]

Looks like we do need the index.md file:

Gatsby.js development 404 page
There's not a page or function yet at /doc/command-reference/data

[shcheklein]

@skshetry pls check the Contributing section:

  {
    "label": "Contributing",
    "slug": "contributing",
    "source": false,
    "children": [
      {
        "label": "DVC Core Project",
        "slug": "core"
      },
      {
        "label": "Docs and Website",
        "slug": "docs"
      },
      {
        "label": "Writing Blog Posts",
        "slug": "blog"
      }
    ]
  },

[skshetry]

Thanks @shcheklein. I have deleted the index.

[skshetry]

All of the conversations are resolved, and the index file is now removed. I am merging this, if there’s anything, let me know. I am happy to work on top. And thankyou for the all the suggestions and help. 🙏🏼

[jorgeorpinel]

Hi. A couple post-merge questions (based on existing conversations).

should we just drop the index page for now and to simplify this?

Since there's no index for this command's base, should we just list data status directly in the nav? No need for the parent data link (if we expect more subcommands we can fix it later)

On the other hand, not having an index.md breaks the existing pattern and is technically incomplete since you can dvc data (-h).

Would it be useful to directly compare to git status? show how it might be useful over the existing dvc status

At least mentioning the difference with dvc status would be great, and link back and forth between both refs. And/or these things could be explained in the index.md page if we restore it, along with some other general motivation.

[shcheklein]

At least mentioning the difference with dvc status would be great, and link back and forth between both refs. And/or these things could be explained in the index.md page if we restore it, along with some other general motivation.

makes sense!

On the other hand, not having an index.md breaks the existing pattern and is technically incomplete since you can dvc data (-h).

let's keep it simple for now? that page is not useful at all ... and let's keep the hierarchy in place, also for simplicity and for consistency

[shcheklein]

@jorgeorpinel could you please distill what is actually important here and doesn't require changes to the DVC repo and make a PR to review? a lot of changes, lots of them very cosmetic, and I'm not sure if there is a reason behind them ... reviewing them takes time

[jorgeorpinel]

keep it simple for now? that page is not useful at all

The cmd group index pages can be useful e.g. see https://dvc.org/doc/command-reference/params as a short version of the guide for people who just want to have enough context to use the feature. Not sure whether we need that for data though. Up to the DVC team!

[jorgeorpinel]

please distill what is actually important here

Started https://github.com/iterative/dvc.org/pull/3924 and resolved the things I included there.

doesn't require changes to the DVC repo

Nothing I added so far, but these string changes are typically pretty easy to propagate to the core repo in my experience.