Specify version of yaml spec to use

Decision

Add version selection to schema. Schema version selection only uses major version, minor version is too granular. Current version is 1.0, work to complete spec will be under 2.0

Work required:

• Add version selection to all schema versions of the config file
• Work out a pattern to add multiple version parsing to the config file. How do we share config options that don’t change? How do we share config options that changed a little? Does class based schema validation work best?
• Make an implied version 1.0 of the config file schema. I’m not sure if we also need schema tests for version 1.0, but it might also make sense to define the spec well.

Original Question

I didn’t find anything related to this on this repo and on the other, so I creating this issue here due https://github.com/rtfd/readthedocs-build/issues/46.

I think would be nice if we allowed to specify the version of the spec used, so this way we can introduce breaking changes to the spec without to worry about previous projects to fail.

We can use semver perhaps?

And something like this on the yaml

Use specific version

version: 2.1
python:
    ...

Use version with latest minor patch

version: 2
python:
    ...

[agjohnson]

We can probably keep the build logic where it is, and just use conditional logic around the existing build code. The most important part is that we have a config object that knows what features it supports, and how to parse/validate those config values. Here’s a psuedo code example:

https://gist.github.com/agjohnson/70a2b5e839bc8e7fd722f8eaf63d6676

[agjohnson]

+1 on major version, if only to reduce the number of specs we’re supporting. We will have a lot more backwards incompatible changes to support here though, so I think a lot of changes will be bumping major versions anyways. New feature additions to the spec shouldn’t break anyone’s config.