diff: update docs according to the new patch

[ghost]

TODO for this PR:

• diff: update docs according to the new patch #953 (comment)

[shcheklein]

@jorgeorpinel @MrOutis I'll take this over and get it done.

@jorgeorpinel please, focus on the existing backlog.

[jorgeorpinel]

Thanks Ivan. I just want to post the link to the original PR: treeverse/dvc/pull/3229

Also, there will probably be some conflicts here or in #933, depending on which one is merged first.

p.s. these changes don't seem to be released yet in latest the version, 0.82.6 – may want to keep that in mind before merging

[jorgeorpinel]

Someone on Discord just noticed this doc is outdated. Should we bump the priority up a little? I can take it if needed.

[shcheklein]

@jorgeorpinel I'm on it. let's get api done (i'll try to review it soon), and then switch to updating get started and other new stuff.

[shcheklein]

The next iteration will be done after we get more clarify on how it should actually behave in certain cases - see treeverse/dvc#3386 and treeverse/dvc#3385 .

Also, I would like to reconsider the way we do examples (with all these expandable sections). It's time to utilize Katacoda or other online services. For each example there should be a link to go and try online (which includes the instruction on how it was setup in the first place). This way we can decouple and simplify examples we write.

[jorgeorpinel]

Full review of the changes so far below. Thanks!

[jorgeorpinel]

dvc diff does not have an effect... when dvc init was used with the --no-scm option

Somewhat unrelated but actually, I checked and this isn't correct. You can create a git repo, then a dvc init --no-scm in it, dvc add a data file, commit (A); change and dvc add the data file again, commit (B), and dvc diff HEAD^ will work.

Is this buggy behavior? If not, we just need to rewrite the paragraph above to something more correct.

[shcheklein]

it feels more or less correct to me - the main thing here is when the repository is not tracked by Git. In your example it is tracked by Git, right? unless I'm missing something.

[jorgeorpinel]

Yes it's tracked by Git, but I initialized the DVC project with dvc init --no-scm. The paragraph above reads ...`dvc diff` does not have an effect... for example when `dvc init` was used with the `--no-scm` option but it does have an effect, as long as there is a Git repo underneath. Maybe just remove the part about --no-scm in the paragraph?

[shcheklein]

It's fine, I still don't see a problem. It's intuitively clear what does it mean, even if implementation is not 100% correct and allows to have a mix of Git and --no-scm.

[jorgeorpinel]

Hmmm OK but just removing that last incorrect statement wouldn't hurt either.

[jorgeorpinel]

Oh and from treeverse/dvc#3229 the only thing that's not reflected in the cmd ref is "Allow running dvc diff when there's no cache available." but not sure it's worth mentioning in docs.

[shcheklein]

@jorgeorpinel

We could do that in a separate PR @shcheklein ?

yes, it'll be a separate PR for sure! We need to merge it sooner.

But it also sounds like a separate and larger task.

it's not that large, we just need to start doing this step by step. I'll create a separate section on Katacoda to define structure and create examples for dvc diff - I think it takes half of the day first time, but then it'll be even easier to reuse them then writing a lot of stuff over and over again.

[shcheklein]

For the record, created a few tickets regarding the cache-less behavior. To be honest both look like a bug for me - treeverse/dvc#3392 and treeverse/dvc#3391

[jorgeorpinel]

Yes it's tracked by Git, but I initialized the DVC project with dvc init --no-scm. The paragraph above reads ...`dvc diff` does not have an effect... for example when `dvc init` was used with the `--no-scm` option but it does have an effect, as long as there is a Git repo underneath. Maybe just remove the part about --no-scm in the paragraph?

[jorgeorpinel]

No strong opinion about these last few details (above ⬆️).