README update guidelines have unclear version paths

[annettejanewilson]

The upgrade guidelines have sections for upgrading:

• from version 0.21.0 to 1.0.0 - makes sense
• from version 0.20.0 to 0.21.0 - also makes sense
• from version 1.0.0-rc.3 to 0.20.0 - this is very confusing

I think now from reading the compatibility matrix that "v1.0.0-rc.3" is genuinely a version number that occurred between 0.18.0 and 0.20.0? If so that's surprising and confusing enough that I feel like it needs to be called out explicitly. As it is, reading the README I thought there was a mistake.

For context I'm currently reading this with an eye to updating code currently using API version 0.18.0 to use API version 1.0.3, and it does indeed break because it looks for api.getSpan in the wrong place. But it took me a while to understand what the upgrade guidelines were telling me.

[vmarchaud]

I'm not sure i understand exactly the problem here, do you want us to explain versions order ?

[annettejanewilson]

Okay, let me start over. I have various pieces of code written by different people that depends on version 0.18.0 of the opentelemetry API. I already know that if I blindly update the opentelemetry API to the newest version, this code crashes. So I know there are definitely API changes I need to worry about in here. The first thing I want to do is find out what those API changes are. So I look at the README. Looking at this table, I'm not even sure if it reads from top to bottom or bottom to top, or if some of them somehow include the others, which would be odd but I guessed that maybe could happen if one version introduced a change and another reverted it. The numbers don't even seem to form a sequence - it looks like they bounce around. Without referring to other sources I cannot figure out what I need to know, which is that all of the listed changes apply to upgrading from version 0.18.0 and that I may also encounter undocumented API changes that occured between 0.18.0 and 1.0.0-rc.3. This was a poor experience and I wanted to improve this for others coming after.

Things I think might help would be:

• Using a full phrase for each heading, like "Upgrading from 0.21.x to 1.0.0", to remove uncertainty.
• Noting that v1.0.0-rc.3 is am out of order version number, with a link to the compatibility matrix or to an explanation of why it's like that.

Of course, I don't know why it's like that! Maybe I am still misunderstanding something. I was just hoping that either you would change the README or indicate what kind of PR you would accept.

[dyladan]

I agree the 0.x and rc versioning story for the trace API was not handled well. There were reasons at the time but I know that doesn't really help when you just need your code to work. We will make sure to take the learnings and roll out future APIs like metrics and logs in a more straighforward manner. The 0.x and rc versions of the APIs are long past so I'm going to close this issue.