Version distinction for API breaking changes vs schema breaking changes

[kim-tsao]

Which area/kind this issue is related to?

/area api

Issue Description

Opening this issue as a result of a discussion we had about introducing breaking API changes that do not affect the schema structure. For example, this bug fix will change the way our clients retrieve boolean properties but if we increase the API version, that would imply structural/design changes with the schema which is not the case. Do we need to consider having a separate versions for:

1. Schema specific changes
2. API interface changes

[kim-tsao]

Seems like this topic was discussed in the past. Slide 3 in this deck talks about supporting two different versions for the API and schema. This was referenced in #150

We also have a version and release process that is still under proposal: https://github.com/devfile/api/blob/main/docs/proposals/versioning-and-release.md

[kim-tsao]

By splitting the API release version from the devfile release version, we could have the following, potential scenarios:

We discussed a few options in our team meeting and decided that the following was the best approach:

• Continue with development on the main branch and create a new API release branch if we are delivering major, non-schema breaking changes that require a major version bump.
• There's the potential for dual maintenance if we are working towards a major release and find a breaking API change in the current release, at which point we would then create a new branch and deliver changes back to main.
• Since dev is done on the main branch, consumers would run into a known versioning bug: Incorrect api version is generated from "go get github.com/devfile/api/v2@main" command #599. Interim versions would incorrectly appear as "v2xxx" rather than the latest "vX" API version. We should document this limitation and make it clear that even though the versioning is incorrect, the latest code is in the main branch

At this point, we will not take any actions to split the versions until there is an absolute need to but there are some TODOs I will address before closing this issue:

• Document this approach in our https://github.com/devfile/api/blob/main/RELEASE.md for reference
• Update this Devfile API Technical Meeting presentation. It's our reference material and it wasn't clearly stated that our JSON schema is GA even though it's generated from the K8s API which is still in alpha release. Added this info to the Release doc since it's easier to find than being buried in a presentation