Document that yaml files are expected to be in YAML v1.2

[skshetry]

After this pending PR iterative/dvc#4415, all YAML files will be expected to be in YAML1.2.

Unless they were hand-written, it should not break anyone's workflow.

The workaround will be to add YAML version directive to the top of the file (though on dvc metrics/params with --revs, they might see wrong values or values of wrong types because of the git history involved but should be very rare).

[jorgeorpinel]

Interesting. Is there a changelog or better doc that explains the main differences between <1.2 and >=1.2 ?

The workaround will be to add YAML version directive to the top of the file

Can you explain this a little further? Where are these directives explained, what YAML files? Example? Thanks

[skshetry]

You can check the list of differences here: https://yaml.readthedocs.io/en/latest/pyyaml.html#defaulting-to-yaml-1-2-support

1. Y/N/on/off/yes/no are boolean in 1.1, but strings in 1.2.
2. Octal numbers and sexagesimal numbers are not supported in 1.2.
3. \/ escape sequences (should not be a big issue here).
4. correct parsing of exponentials: this is what made us move to 1.2. In YAML 1.1, 3e4 (notice no dot before mantissa) is a string, but in 1.2 and in JSON, it's an exponential number. Similarly, pyyaml has a bug in which it fails to parse 3.0e4 in yaml 1.1, it needed sign compulsorily (3.0e+4 would work).

1 and 2 should not be a problem if DVC dumped them, but if it's hand-written and DVC never overwrote them, there might be an issue.
4 is backward incompatible but depends on how you see it. It won't be parsed as a string, which is incompatible as per spec.

You have to use yaml version directive to force versions:

% YAML 1.1

[jorgeorpinel]

correct parsing of exponentials: this is what made us move to 1.2

Sounds like we should focus on adding notes about this specific feature in docs, where needed.

We can also specify YAML 1.2 somewhere but that seems less relevant since it's been the stable version for over 10 years. (Why did we even use 1.1? 😬)

You have to use yaml version directive to force versions

OK. But again, can you explain this? What is a version directive? Where is it documented? How is it a workaround and workaround for what? Etc.

Thanks

[skshetry]

Why did we even use 1.1?

@jorgeorpinel, the most popular library in python is pyyaml which still does not support 1.2 and is largely unmaintained, and since 1.1 is almost 20 years old, it's quite optimized and is twice as faster. We are sacrificing that speed.

What is a version directive?

You just have to start your YAML document with:

% YAML 1.1
---

https://yaml.org/spec/1.2/spec.html#id2781553

[jorgeorpinel]

OK. About "YAML" directives, there are still open questions @skshetry . Again, can you explain this a little further please? We can't document something that isn't fully understood.

How is it a workaround and workaround for what? Who would add them and to which files? Examples?

Thanks!