This is a follow up of previous community meeting.

Today, we coupled release of OAM spec with apiVersion of the object, for example, in v1.0.0-alpha.2 release, all the objects will have apiVersion: v1alpha2, and in v1.0.0-alpha.1 release, all the objects had apiVersion: v1alpha1.

This is actually very challenging for OAM to be adopted in production env because release and apiVersion are two different things.

apiVersion in Kubernetes Resource Model which OAM adopted, is used to track version and change to the object fields. Specifically, a break change will require the object to upgrade to a new apiVersion. Also, the alpha/beta means different maturity levels of the API. Beta means stable, feature enable by default and backward compatibility must be guaranteed for 3 releases if breaking change introduced (i.e. corresponding code must work for multiple versions of the object).

So the issue is, we are essentially indicating that every release of OAM spec is a breaking change now (and in practice users are suffering from apiVersion must be upgraded in every release).
With OAM spec becoming stable and we now have OAM kubernetes runtime for user to install, this could be fixed.

So ideally as a user, if there's no breaking change in the objects fields, I should be able to upgrade my whole OAM platform to next release of OAM spec by upgrading my oam-k8s-runtime lib/controller smoothly.

Proposal

• OAM spec version should be different from apiVersion. I'd suggest we adopt Semantic Versioning 2.0.0 i.e MAJOR.MINOR.PATCH.
  • change needed: v1.0.0-alpha.1 -> v0.1.0, v1.0.0-alpha.2 -> v0.2.0, and next release should be v0.3.0 or even v1.0.0.
  • the v1.0.0 of OAM spec will be treated as stable, i.e. all objects apiVersion will be promoted to beta. Before that, the apiVersion will follow rules defined by k8s api convention
  • spec README will have a full list of releases (release branches) and working draft branch (master branch)
    • we can make the latest release branch as the default branch of course.
• oam-k8s-runtime will have its own release (every month), and its readme will clearly clarify which release of OAM spec it compliant with. For example: