Improved file_format documentation

[marcalff]

Improved the documentation for file_format.

Point to the yaml schema definition, which helps when editing the configuration file.

Also, fixed typos ("nand" -> "and", "ot" -> "to").

[codeboten]

Thanks @marcalff, it occurred to me as I was reading this that the file_format and the release version number differ.

We should fix this to be consistent.

[marcalff]

Thanks @marcalff, it occurred to me as I was reading this that the file_format and the release version number differ.

We should fix this to be consistent.

I assume you mean file_format: 0.3 versus tag v0.3.0.

This relates to the discussion about:

• Should file_format follow semantic versioning? #2

where we need to define when major/minor/patch versions are incremented.

In my opinion, we need a way to make a new release that can contain:

• more documentation
• spelling fixes
• more test cases
• fixes in CI, makefiles, etc

that is, release everything except changes to the yaml schema itself, without forcing users to do a version bump in their own config.yaml.

If we reserve patch version for these changes, then for example, a new release of this repo, tagged v0.3.1, can contain more documentation (this very PR) compared to previous release v0.3.0, while users refer to file_format: 0.3.

So, the fact that a release uses MAJOR.MINOR.PATCH, while a config.yaml refers to a MAJOR.MINOR schema, looks ok to me: on the contrary, we need this discrepancy to deliver changes that do not affect the yaml schema.

[jack-berg]

Looks good. If no objections, I can merge.