GTO: updating docs #235
GTO: updating docs #235
Conversation
aguschin
added
A: docs
Link Check ReportThere were no links to check! |
| ## Git tag message format | ||
| ## Git tags format |
There was a problem hiding this comment.
But it's really the tag's annotation message that has a format right? Not all tags are annotated in Git (in fact it's rare to use annotated tags, I think) so this could be confusing/misleading wording.
There was a problem hiding this comment.
No, it's Git tag name. E.g. to register a version, you need a Git tag called [email protected], annotated with some message. It could be annotated with any text, but without a text annotation it would be a lightweight tag, not an annotated one (and GTO ignores lightweight tags). For example, see https://github.com/iterative/example-gto/tags
[email protected] is a tag name and Registering artifact churn version v3.1.1 is a Git tag message.
There was a problem hiding this comment.
It could be annotated with any text, but without a text annotation it would be a lightweight tag...
I see. May I ask why does GTO ignore lightweight tags?
There was a problem hiding this comment.
Sure, we had a discussion about it here iterative/gto#127
Co-authored-by: Jorge Orpinel <[email protected]>
| files instead. | ||
| practice, you should consider not committing your artifacts to Git. Instead, | ||
| [use DVC](/doc/gto/user-guide/dvc), Git-lfs, or any method to commit pointers to | ||
| the binary files instead. | ||
|
|
||
| ## Annotations in artifacts.yaml |
There was a problem hiding this comment.
Minor but I'm a bit worried about the use of term annotation here (and in gto annotate) given that Git tags also have annotations AND since we specifically use annotated Git tags only. May be confusing (esp. for users familiar with Git tags).
There was a problem hiding this comment.
Yep. Don't remember why we decided on using "annotations" considering this collision.
| ## Tracking an artifact with DVC | ||
|
|
||
| First, we need to start tracking artifact with DVC. If you produce this artifact |
There was a problem hiding this comment.
I don't think we need this section at all: it's DVC documentation (redundant since we already linked to the Get Started)...
There was a problem hiding this comment.
But, this tells the bare minimum so people could understand the full workflow. DVC GS is quite huge, so just redirecting there without any context would be confusion. Do you disagree?
There was a problem hiding this comment.
Besides, this shows dvc import-url, which could be an important scenario for some folks starting to use MR while having some models outside.
There was a problem hiding this comment.
People without context will get the bare minimum from this part. People with context will just see some story here.
There was a problem hiding this comment.
I think that linking to https://dvc.org/doc/start/data-management/data-versioning or even straight to https://dvc.org/doc/command-reference/add would be acceptable.
Not a super strong opinion since this section is small, but I think that in principle we should not cross-document products. Logic: what if the DVC feature changes? dvc.org/doc will probably get updated, but not here.
Besides, this shows dvc import-url
Not seeing why that's particularly important. BTW, the blocks are missing git add .gitignore
jorgeorpinel
added
C: user-guide
|
Ping @aguschin. Need help moving this fwd? |
Co-authored-by: Jorge Orpinel <[email protected]>
Co-authored-by: Jorge Orpinel <[email protected]>
Co-authored-by: Restyled.io <[email protected]>
New pages:
TODO:
dvcintegration inexample-gtorepo - probably in a newdvcbranchexample-gtorepo to update the GTO+DVC page