Clarify compatibility and content negotiation

[krajorama]

Following the dev summit on 13th September in Berlin.

https://docs.google.com/document/d/1uurQCi5iVufhYHGlBZ8mJMK_freDFKPG0iYBQqJ9fvA/edit#bookmark=id.kj599un8yoj7

From the dev summit document:

CONSENSUS: We intend to add native histograms as a part of OpenMetrics 1.1. A major version bump is not required.
CONSENSUS: We agree that the understanding of backwards compatibility is that a A.y parser can also parse an A.x format. But the A.x parser doesn’t need to parse the A.y format. Where y > x, A, x, y being integers
CONSENSUS: OpenMetrics doesn’t need a major version bump if the changes are backwards compatible.

Notes:

• this is my understanding
• I'm suggesting a more comprehensive update than agreed in the dev summit
• I think the document should actually state its own version (1.0.0) , but I'll leave that to a different PR

[RichiH]

Thanks!

I did a first run; I am currently unsure if we should have the version negotiation in the "version" section; the "content negotiation" section might make more sense. MUST 1.0.0 for within 1.x at least, SHOULD do the highest version, and done?

[RichiH]

Suggested change

	Versioning follows a semantic versioning model on the specification level. Breaking semantic changes (for example removal from ABNF) MUST result in major version bump, however additions MUST be in a minor version bump. Multiple changes may be bundled in the same version update and the version bump will be the biggest version bump in those changes.
	Versioning follows a semantic versioning model on the specification level. Breaking semantic changes MUST be signaled with a major version increase. For example, removing a stanza.
	Semantic extensions to the ABNF MUST be signaled with a minor or major version increase. For exmaple, adding a line starting with `# foo`.

[RichiH]

Semantic versioning needs a reference in line 38 and following, now.

[krajorama]

Added to informative references

[RichiH]

I think supporting e.g. 1.0 and 1.5 would be OK.

[krajorama]

I'll remove this line

[krajorama]

I think we should state this explicitly, because that's not what backwards compatibility means. I would expect that a parser can read anything that lower semantic version (on the same major version).

[RichiH]

Suggested change

	Ingestors MUST implement at least version 1.0.0 of the standard.
	Ingestors MUST implement protocol negotiation to be able to support higher than 1.0.0 version.
	If exposer doesn't support content negotiation, version 1.0.0 SHOULD be assumed.
	Ingestors MUST implement version 1.0.0 of the standard.
	Ingestors MAY support versions higher than 1.0.0. In this case, they MUST implement protocol version negotiation.
	In case no protocol version negotiation takes place, version 1.0.0 SHOULD be assumed.

[RichiH]

We can change the "MUST 1.0.0" to "SHOULD 1.0.0" in 2.x if we need to. It's a bit of a cop-out, but long term, say Prometheus 4.0, it might be defensible.

[krajorama]

Maybe, but I'm not sure we'll ever be able to get rid of 1.0.0

[RichiH]

That seems self-evident?

[RichiH]

But they SHOULD negotiate the latest version as well?

[krajorama]

This is pretty academic, as negotiation currently takes place in the exposer, but the alternative would be to try and parse the content as 1.0.0.

I'll remove it as not very useful for now.

[krajorama]

@RichiH I've moved this PR to draft, because of two things:

1. Now it doesn't say explicitly what the dev summit agreed on: "CONSENSUS: We agree that the understanding of backwards compatibility is that a A.y parser can also parse an A.x format. But the A.x parser doesn’t need to parse the A.y format. Where y > x, A, x, y being integers." In particular if something as backwards compatible, then my originally suggested statement that parser for 1.5 must be able to parse 1.0, 1.1, 1.2, 1.4 as well stands.
2. Not sure what to do with the specification/draft-richih-opsawg-openmetrics-00.txt and specification/draft-richih-opsawg-openmetrics-01.txt files.