ref: data status

[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]

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.

[shcheklein]

Thanks. @skshetry , and thank for keeping it simple first.

We'll need to do a few iterations here and I have some product questions, would love your feedback on that.

[dberenbaum]

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

[shcheklein]

Approving so that it's not blocked on me. There are still some pending minor discussions - like removing index page for now.

[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

[jorgeorpinel]

we should be able to merge something and follow up later if needed...
if there’s anything, let me know. I am happy to work on top.

Great work so far! Some other possible follow ups:

[jorgeorpinel]

May be a better visual grouping (even if it doesn't match the help output) cc @dberenbaum

Suggested change

	usage: dvc data status [-h] [-q | -v]
	[--granular] [--unchanged]
	[--untracked-files [{no,all}]]
	[--json]
	usage: dvc data status [-h] [-q | -v] [--json] [--granular]
	[--unchanged] [--untracked-files [{no,all}]]

[shcheklein]

doesn't look important to me

[jorgeorpinel]

It's probably secondary, yes. It's a quality-related best practice for the cmd ref/ usage blocks we started applying recently, see #3345.

[jorgeorpinel]

Suggested change

	The `data status` command displays the state of the working directory and the
	changes with respect to the last Git commit (`HEAD`). It shows you what new
	changes have been committed to DVC, which haven't been committed, which files
	aren't being tracked by DVC and Git, and what files are missing from the
	<abbr>cache</abbr>.
	The `dvc data status` command only outputs information, it won't modify or
	change anything in your working directory. It's a good practice to check the
	state of your repository before doing `dvc commit` or `git commit` so that you
	don't accidentally commit something you don't mean to.
	An example output might look something like follows:
	Displays the state of the <abbr>workspace</abbr> compared to the last Git commit
	(`HEAD`). This includes committed and uncommitted additions, updates, and
	deletions of DVC-tracked files. Checking the state of your tracked data is
	useful to know what to `dvc add` (or `dvc commit`) and `git commit`. Example:

[shcheklein]

wha -> what

it was fine before I think, don't see a reason to change this

[jorgeorpinel]

reason to change this

Minor but not cosmetic: Reduced from 3 paragraph Desc. intro to 1. (We want explanations in refs to stay short.) I also removed some sentences that aren't needed IMO. Applied some other existing patterns (e.g. don't mention the command name at the beginning so it's not repetitive later when you need it in other paragraphs).

[shcheklein]

Applying existing patterns is fine, everything else feels very cosmetic still + changes the meaning / original intention (which is fine, but we don't have strong enough reason to spend time reviewing this to my mind in this case and debate one more time about intentions in the text, benefits, etc, etc). Please, unless it's super important let's not do this - it takes a lot of time to review it.

[jorgeorpinel]

Agreed. I'm making a point to spend time on these for now just to compile mayor existing practices (example).

[jorgeorpinel]

So if it's tracked by EITHER DVC or Git it will not be included here?

[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 #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.