What's needed?

At the moment we are making breaking changes in the v1 namespace in v0.x.x, soon to be v0.7.0. This means all APIs depending on this repo (basically all of them) will need to be updated at the same time to be able to work together. This is a huge issue as will require a lot of coordination.

Proposed solution

1. Move the current v1 directory to v1alpha7 (let's use 7 from v0.7.0 for extra clarity).
2. Copy the v1 directory as it was in v0.6.x to v0.x.x
3. People using v0.x.x change their imports to use v1b7 instead of v1
4. Release v0.7.0 (whenever is ready)
5. Once everybody upgraded to v0.7.0 (i.e. are importing from v1b7), we can remove v1 (and the top-level stuff).
6. We continue adding v1alpha8 for v0.8.0, etc. until we reach v1.
7. Just before the final v1 release (v1.0.0) we copy v1alphaX (the latest one, of course) to v1.
8. We release (v1.0.0)
9. After everybody upgraded to v1.0.0 (and is using the new v1 exclusively), we can remove any remaining old v1alphaX in a subsequent release.

The naming of the namespaces is based on Google's guideline on release-based API versioning.

Additional context

Google already define very useful guidelines around this issue:

API Versioning

API Versioning describes the versioning strategies used by Google APIs.

Summary:

• Channel-based versioning: A stability channel is a long-lived release at a given stability level that receives in-place updates. There is no more than one channel per stability level for a major version. Under this strategy, there are up to three channels available: alpha, beta, and stable.

  The alpha and beta channel must have their stability level appended to the version, but the stable channel must not have the stability level appended. For example, v1 is an acceptable version for the stable channel, but v1beta or v1alpha are not.

• Release-based versioning: An individual release is an alpha or beta release that is expected to be available for a limited time period before its functionality is incorporated into the stable channel, after which the individual release will be shut down. When using release-based versioning strategy, an API may have any number of individual releases at each stability level.

  Alpha and beta releases must have their stability level appended to the version, followed by an incrementing release number. For example, v1beta1 or v1alpha5. APIs should document the chronological order of these versions in their documentation (such as comments).

• Visibility-based versioning: API visibility is an advanced feature provided by Google API infrastructure. It allows API producers to expose multiple external API views from one internal API surface, and each view is associated with an API visibility label.

Stability levels

Stability levels summary:

• Alpha: An alpha component undergoes rapid iteration with a known set of users who must be tolerant of change. The number of users should be a curated, manageable set, such that it is feasible to communicate with all of them individually.

• Beta: A beta component must be considered complete and ready to be declared stable, subject to public testing. Beta components should be exposed to an unknown and potentially large set of users. In other words, beta components should not be behind an allowlist; instead, they should be available to the public.

• Stable: A stable component must be fully-supported over the lifetime of the major API version. Because users expect such stability from components marked stable, there must be no breaking changes to these components.

So the proposed solution uses alpha because we are mostly doing this with a small group of known users and going through rapid iteration, but we might do some beta releases before going to v1.0.0 if we want to expose this to a more general audience before declaring it stable.

Backwards compatibility

Backwards compatibility defines what constitutes a backwards compatible change and what constitutes a backwards incompatible change.