`exp`: misc. guide and ref. updates #3080

jorgeorpinel · 2021-12-10T17:53:24Z

Extracted from #2909

More concrete description of what exp apply does
Remove some implementation details from exp run (now in the UG)
Move How-to after Exp Mgmt in UG
Single place for info. about "persisting" experiments
Reword/ clarify https://dvc.org/doc/user-guide/troubleshooting#git-auth
Other misc. edits (clean Markdown, add tooltips, links to guide, etc.)

PENDING?

Is the current exp apply behavior documented here intended or a bug?
See exp: misc. guide and ref. updates #3080 (review) below.

* guide: add DVC Experiments page and links + some copy edits * guide: remove checkpoint related changes * guide: remove `dvc experiments` long cmd autolinks per #2901 * guide: move run-cache section back to Exp Mgmt index bottom per #2909 (review) * guide: Exp Mgmt/ DVC Exps -> Exps Overview per #2909 (review) * guide: clear separation between Exp Mgmt index and Overview page rel #2909 (comment) * guide: single guide for Persisting Exps content and fix links * guide: begin extracting Exp details from Running to Overview rel #2909 (comment) * guide: make ToC entry for Run Cache section rel #2909 (comment) * Update content/docs/user-guide/experiment-management/index.md Co-authored-by: Ivan Shcheklein <shcheklein@gmail.com> * [NESTED] guide: Exp implementation details, naming into Overview (#3006) * guide: bring exp implementation details and naming from ref. per #2909 (review) * guide: copy edits to exp naming info. * guide: emphasize dvc exps are not part of Git tree in overview rel #2909 (review) * guide: ID->name in dvc exps overview per #2909 (review) * guide: ID->name in other exp guides rel #2909 (review) * guide: Visualize->Review in exp/overview/basic-workflow per #2909 (review) * guide: don't say "cleans the slate" in exp/overview/basic-workflow per #2909 (review) * giude: soften params description in exps index per #2909 (review) * guide: generalize dvc exps basic workflow * guide: Properties section in DVC Exps overview page * guide: exp init section in Exp Overview page * guide: clarify dvc exp implementation * guide: expand on Exp Overview motivation per #2909 (comment) * guide: direct language in Exp Overview/ workflow intro per #2909 (comment) * guide: mention metrics in exp init intro (Exp Overview) per #2909 (comment) * guide: intro exp init before giving specific examples of what it does per #2909 (comment) * guide: hint forach stages for hybrid exp org pattern rel. #2909 (comment) * guide: exp mgmt index copy edits * guide: mention label-based exp organization rel. https://docs.google.com/presentation/d/1C_owNoC72GvrpyMGlonHEYJ9I2rl2SLHkZQDMx0eT7A/edit#slide=id.gcb78e52e40_0_635 * guide: hide exp naming section in overview page and other details per #2909 (comment) et al. * guide: mention `exp init -i` in Overview per #2909 (comment) * guide: typo fix per #2909 (comment) * ref: exp apply copy edits per #2909 (review) * ref: mention init before exp init per #2909 (review) * guide: correct info aboug exp init in Exp Overview per pending comments in #2909 (review) * ref: link from exp init to corresponding guide * guide: make exp intro more concrete per #2909 (comment) * guide: rewrite exp init section of Exps Overview page per #2909 (review) * ref: roll back unrelated ref changes (moved to ref/exp-misc) * guide: roll back unrelated changes (moved to #3080) Co-authored-by: Ivan Shcheklein <shcheklein@gmail.com>

iesahin

a few minor points but looks good in general, thanks. 👍🏼

content/docs/command-reference/exp/apply.md

content/docs/command-reference/exp/branch.md

content/docs/user-guide/experiment-management/comparing-experiments.md

rel. #3080 (comment)

per #3080 (comment)

rel. #3080 (comment)

content/docs/command-reference/exp/branch.md

jorgeorpinel · 2021-12-21T08:37:34Z

Mind double checking the DVC behavior explanations when you can @dberenbaum ?

dberenbaum · 2021-12-22T17:23:53Z

content/docs/command-reference/exp/apply.md

+⚠️ This command will destroy any existing changes in the workspace (Git working
+tree) unless the `--no-force` flag is used.


Hmm, I'm pretty sure the old text is the intended behavior, but I can confirm that the changes match the current behavior. Reopened iterative/dvc#6930 (comment) to clarify.

I see iterative/dvc#6930 was marked as a bug so I'll revert this explanation @dberenbaum ... ⌛

Done in b2bcddc.

content/docs/command-reference/exp/apply.md

per #3080 (comment)

iesahin

minor

iesahin · 2021-12-23T11:17:19Z

content/docs/command-reference/exp/apply.md

-used.
+Specifically, `dvc exp apply` checks out any files or directories needed to
+reflect the experiment conditions and results. This can include both with DVC
+and Git: code, data, <abbr>parameters</abbr>, <abbr>metrics</abbr>, etc.


I think the previous expression is more clear.

I don't love the 2nd sentence here either if that's what you mean @iesahin. But the previous wording was a single long sentence instead of 2 which mixed the 2 ideas so it was harder to read and comprehend IMO. I also changed "restores" for "check out" to be more specific about the operation what takes place.

p.s. I think I clarified the wording now (817d6ee).

per #3080 (review)

* guide: add DVC Experiments page and links + some copy edits * guide: remove checkpoint related changes * guide: remove `dvc experiments` long cmd autolinks per #2901 * guide: move run-cache section back to Exp Mgmt index bottom per #2909 (review) * guide: Exp Mgmt/ DVC Exps -> Exps Overview per #2909 (review) * guide: clear separation between Exp Mgmt index and Overview page rel #2909 (comment) * guide: single guide for Persisting Exps content and fix links * guide: begin extracting Exp details from Running to Overview rel #2909 (comment) * guide: make ToC entry for Run Cache section rel #2909 (comment) * Update content/docs/user-guide/experiment-management/index.md Co-authored-by: Ivan Shcheklein <shcheklein@gmail.com> * [NESTED] guide: Exp implementation details, naming into Overview (#3006) * guide: bring exp implementation details and naming from ref. per #2909 (review) * guide: copy edits to exp naming info. * guide: emphasize dvc exps are not part of Git tree in overview rel #2909 (review) * guide: ID->name in dvc exps overview per #2909 (review) * guide: ID->name in other exp guides rel #2909 (review) * guide: Visualize->Review in exp/overview/basic-workflow per #2909 (review) * guide: don't say "cleans the slate" in exp/overview/basic-workflow per #2909 (review) * giude: soften params description in exps index per #2909 (review) * guide: generalize dvc exps basic workflow * guide: Properties section in DVC Exps overview page * guide: exp init section in Exp Overview page * guide: clarify dvc exp implementation * guide: expand on Exp Overview motivation per #2909 (comment) * guide: direct language in Exp Overview/ workflow intro per #2909 (comment) * guide: mention metrics in exp init intro (Exp Overview) per #2909 (comment) * guide: intro exp init before giving specific examples of what it does per #2909 (comment) * guide: hint forach stages for hybrid exp org pattern rel. #2909 (comment) * guide: exp mgmt index copy edits * guide: mention label-based exp organization rel. https://docs.google.com/presentation/d/1C_owNoC72GvrpyMGlonHEYJ9I2rl2SLHkZQDMx0eT7A/edit#slide=id.gcb78e52e40_0_635 * guide: hide exp naming section in overview page and other details per #2909 (comment) et al. * guide: mention `exp init -i` in Overview per #2909 (comment) * guide: typo fix per #2909 (comment) * ref: exp apply copy edits per #2909 (review) * ref: mention init before exp init per #2909 (review) * guide: correct info aboug exp init in Exp Overview per pending comments in #2909 (review) * ref: link from exp init to corresponding guide * guide: make exp intro more concrete per #2909 (comment) * guide: rewrite exp init section of Exps Overview page per #2909 (review) * ref: roll back unrelated ref changes (moved to ref/exp-misc) * guide: roll back unrelated changes (moved to #3080) Co-authored-by: Ivan Shcheklein <shcheklein@gmail.com>

* ref: bring changes from #2909 * guide: bring changes from #2909 * exp: pull some changes from #2908 * ref: better explain exp apply behavior explicitly rel. #3080 (comment) * ref: exp apply destroys any canges per #3080 (comment) * ref: clarify that exp branch makes 1+ commits in the exp branch rel. #3080 (comment) * ref: link exp apply -> exp branch per #3080 (comment) * ref: clarify (again) what applies does specifically per #3080 (review) * ref: document intended apply behavior on conflicting changes per #3080 (review)

jorgeorpinel added 2 commits December 10, 2021 10:48

ref: bring changes from #2909

9ec36f2

guide: bring changes from #2909

d0b46c3

jorgeorpinel added a commit that referenced this pull request Dec 10, 2021

guide: roll back unrelated changes (moved to #3080)

c088a06

shcheklein temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 10, 2021 17:53 Inactive

jorgeorpinel mentioned this pull request Dec 10, 2021

guide: DVC Experiments Overview #2909

Merged

5 tasks

jorgeorpinel self-assigned this Dec 10, 2021

Merge branch 'master' into ref/exp-misc

4ae99db

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 15, 2021 00:57 Inactive

jorgeorpinel changed the title ~~exp: guide and ref. updates [WIP]~~ exp: guide and ref. updates [WIP] Dec 15, 2021

jorgeorpinel marked this pull request as ready for review December 15, 2021 01:31

jorgeorpinel requested a review from iesahin December 15, 2021 01:31

jorgeorpinel changed the title ~~exp: guide and ref. updates [WIP]~~ exp: guide and ref. updates Dec 15, 2021

jorgeorpinel changed the title ~~exp: guide and ref. updates~~ exp: misc. guide and ref. updates Dec 15, 2021

exp: pull some changes from #2908

a029288

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 15, 2021 03:44 Inactive

iesahin reviewed Dec 15, 2021

View reviewed changes

jorgeorpinel mentioned this pull request Dec 15, 2021

guide: revisit Exp Sharing #2908

Merged

2 tasks

jorgeorpinel added 2 commits December 20, 2021 20:53

Merge branch 'master' into ref/exp-misc

0eca57b

ref: better explain exp apply behavior explicitly

49c585c

rel. #3080 (comment)

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 21, 2021 07:51 Inactive

ref: exp apply destroys any canges

220a9b0

per #3080 (comment)

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 21, 2021 08:24 Inactive

jorgeorpinel added a commit that referenced this pull request Dec 21, 2021

ref: clarify that exp branch makes 1+ commits in the exp branch

117a61d

rel. #3080 (comment)

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 21, 2021 08:33 Inactive

ref: clarify that exp branch makes 1+ commits in the exp branch

7c30e28

rel. #3080 (comment)

jorgeorpinel force-pushed the ref/exp-misc branch from 117a61d to 7c30e28 Compare December 21, 2021 08:34

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 21, 2021 08:35 Inactive

jorgeorpinel commented Dec 21, 2021

View reviewed changes

content/docs/command-reference/exp/branch.md Show resolved Hide resolved

jorgeorpinel requested a review from iesahin December 21, 2021 08:36

jorgeorpinel assigned dberenbaum and unassigned dberenbaum Dec 21, 2021

jorgeorpinel requested a review from dberenbaum December 21, 2021 08:37

dberenbaum approved these changes Dec 22, 2021

View reviewed changes

jorgeorpinel added 2 commits December 22, 2021 22:57

Merge branch 'master' into ref/exp-misc

017706c

ref: link exp apply -> exp branch

de850f5

per #3080 (comment)

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 23, 2021 05:58 Inactive

jorgeorpinel requested review from iesahin and removed request for iesahin December 23, 2021 05:59

iesahin approved these changes Dec 23, 2021

View reviewed changes

ref: clarify (again) what applies does specifically

817d6ee

per #3080 (review)

jorgeorpinel deployed to dvc-org-ref-exp-misc-q412dutpu December 23, 2021 18:15 View deployment

ref: document intended apply behavior on conflicting changes

b2bcddc

per #3080 (review)

jorgeorpinel temporarily deployed to dvc-org-ref-exp-misc-q412dutpu December 23, 2021 18:20 Inactive

jorgeorpinel merged commit eb728e6 into master Dec 23, 2021

jorgeorpinel deleted the ref/exp-misc branch December 23, 2021 18:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`exp`: misc. guide and ref. updates #3080

`exp`: misc. guide and ref. updates #3080

jorgeorpinel commented Dec 10, 2021 •

edited

iesahin left a comment

jorgeorpinel commented Dec 21, 2021

dberenbaum Dec 22, 2021 •

edited by jorgeorpinel

jorgeorpinel Dec 23, 2021

jorgeorpinel Dec 23, 2021

iesahin left a comment

iesahin Dec 23, 2021

jorgeorpinel Dec 23, 2021

jorgeorpinel Dec 23, 2021

		⚠️ This command will destroy any existing changes in the workspace (Git working
		tree) unless the `--no-force` flag is used.

exp: misc. guide and ref. updates #3080

exp: misc. guide and ref. updates #3080

Conversation

jorgeorpinel commented Dec 10, 2021 • edited

iesahin left a comment

Choose a reason for hiding this comment

jorgeorpinel commented Dec 21, 2021

dberenbaum Dec 22, 2021 • edited by jorgeorpinel

Choose a reason for hiding this comment

jorgeorpinel Dec 23, 2021

Choose a reason for hiding this comment

jorgeorpinel Dec 23, 2021

Choose a reason for hiding this comment

iesahin left a comment

Choose a reason for hiding this comment

iesahin Dec 23, 2021

Choose a reason for hiding this comment

jorgeorpinel Dec 23, 2021

Choose a reason for hiding this comment

jorgeorpinel Dec 23, 2021

Choose a reason for hiding this comment

`exp`: misc. guide and ref. updates #3080

`exp`: misc. guide and ref. updates #3080

jorgeorpinel commented Dec 10, 2021 •

edited

dberenbaum Dec 22, 2021 •

edited by jorgeorpinel