Merge pull request #382 from resouer/fix-version

Follow up on new versioning mechanism

2.overview_and_terminology.md

@@ -42,7 +42,7 @@ The following terms are used throughout this specification.
 ### Workload Definitions
 
 A platform that implements OAM supplies a runtime (or runtimes) that can execute
-components. Each type of component that can be run by the OAM runtime is represented by a _workloadDefinition_ that describes the following:
+components. Each type of workload that a component can run by the OAM runtime is represented by a _workloadDefinition_ that describes the following:
 
 - Metadata: Information about the workload kind
 - Definition reference: A reference to a schema that defines the workload. The schemas are mostly provided by the OAM
@@ -79,7 +79,7 @@ A trait defines a piece of add-on functionality that pertains to the operation o
 A trait is described as:
 
 - Metadata: Information about the trait
-- Applies-to list: Enumeration of workloads to which this trait applies
+- Applies-to list: Enumeration of workloads types to which this trait applies
 - Definition reference: A reference to a schema that defines the trait
 
 ### Application Scopes
@@ -104,7 +104,7 @@ An application configuration has the following parts:
 
 ## Representing OAM Objects as Schematics
 
-The OAM specification represents OAM objects (workloads, components, trait definitions, application configurations, etc.) as _schematics_.
+The OAM specification represents OAM objects (workload definitions, components, trait definitions, application configurations, etc.) as _schematics_.
 A schematic is a structured document that provides a declaration of an object or an object's desired state. Throughout this specification, schematics are represented in [YAML](https://yaml.org/). However, nothing in this specification precludes the possibility of representing schematics as JSON documents or other similarly structured textual or binary representations.
 
 ### The Structure of a Schematic
@@ -209,7 +209,7 @@ The following annotation labels are _predefined_ and RECOMMENDED.
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
 | `description` | `string` | N | | A short description of the component. |
-| `version` | `string` | N | | A string defining the [semantic version](https://semver.org/) of the component. |
+| `version` | `string` | N | | A user provided string defining the [semantic version](https://semver.org/) of the component, e.g. the release version of this software|
 
 If `version` is not supplied, the default version is assumed to be `0.1.0`, per the [SemVer](https://semver.org/) specification.
 
@@ -229,9 +229,7 @@ The metadata section is used in all schematics. It is also compatible with the K
 
 ## Group, Version, and Kind
 
-Many of the API objects described in this document use a naming scheme called "Group, Version, Kind." This scheme, popularized by Kubernetes, provides a consistent way of namespacing and versioning API objects, and it is used here for OAM API versioning.
-
-> Applications, components, containers, and other entities may have their own versioning schemes. This scheme is solely for the API objects like Component, Application Schematic, Workload, and Traits.
+Many of the API objects described in this document use a naming scheme called "Group, Version, Kind." This scheme, popularized by Kubernetes, provides a consistent way of namespacing and versioning API objects, and it is used here for OAM API objects versioning.
 
 This section describes the scheme.
 

3.workload.md

@@ -18,7 +18,7 @@ Here are the attributes that provide top-level information about the workload de
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
-| `apiVersion` | `string` | Y | | The specific version of the OAM specification in use. The core types use `core.oam.dev/v1alpha2` |
+| `apiVersion` | `string` | Y | | A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification |
 | `kind` | `string` | Y || Must be `WorkloadDefinition` |
 | `metadata` | [`Metadata`](#metadata) | Y | | Information about the workload definition. |
 | `spec`| [`Spec`](#spec) | Y | | A container for the workload definition. |

4.component.md

@@ -18,7 +18,7 @@ These attributes provide top-level information about the component definition.
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
-| `apiVersion` | `string` | Y || The specific version of the OAM specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. |
+| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. |
 | `kind` | `string` | Y || Must be `Component`. |
 | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the component. |
 | `spec`| [`Spec`](#spec) | Y || A specification for component attributes. |

5.application_scopes.md

@@ -48,7 +48,7 @@ These attributes provide top-level information about the scope definition.
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
-| `apiVersion` | `string` | Y || The specific version of the OAM specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. |
+| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. |
 | `kind` | `string` | Y || Must be `ScopeDefinition`. |
 | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the scope. |
 | `spec`| [`Spec`](#spec) | Y || A specification for scope attributes. |

6.traits.md

@@ -63,7 +63,7 @@ The top-level attributes of a trait define its metadata, version, kind, and spec
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
-| `apiVersion` | `string` | Y || The specific version of the OAM specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. |
+| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. |
 | `kind` | `string` | Y || Must be `TraitDefinition` |
 | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the trait. |
 | `spec`| [`Spec`](#spec) | Y || A specification for trait attributes. |

7.application_configuration.md

@@ -59,7 +59,7 @@ The top-level attributes of a application configuration define its metadata, ver
 
 | Attribute | Type | Required | Default Value | Description |
 |-----------|------|----------|---------------|-------------|
-| `apiVersion` | `string` | Y || The specific version of the specification in use. This version of the specification covers `core.oam.dev/v1alpha2`. |
+| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. |
 | `kind` | `string` | Y || Must be `ApplicationConfiguration` |
 | `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the application configuration. |
 | `spec`| [`Spec`](#spec) | Y || A specification for application configuration attributes. |

README.md

@@ -1,9 +1,14 @@
 # Open Application Model Specification
 
+[![Gitter](https://badges.gitter.im/oam-dev/community.svg)](https://gitter.im/oam-devcommunity?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
+[![License: MIT](https://img.shields.io/badge/License-OWF-yellow)](https://github.com/oam-dev/spec/blob/master/LICENSE)
+[![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/oam-dev/spec)](https://www.tickgit.com/browse?repo=github.com/oam-dev/spec)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/oam_dev.svg?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=oam_dev)
+
 |![notification](assets/bell-outline-badge.svg) What is NEW!|
 |------------------|
 |May 18th, 2020. [Crossplane](https://github.com/crossplane/crossplane) becomes the standard Kubernetes implementation of OAM spec!|
-|Mar 27th, 2020. OAM v1.0.0-alpha.2 is **RELEASED**! The new spec is highly extensible and native to Kubernetes runtime. Check the spec and [What's new in OAM v1alpha2](https://speakerdeck.com/resouer/whats-new-in-oam-v1alpha2-spec) for more detail!|
+|Mar 27th, 2020. OAM v0.2.0 is **RELEASED**! The new spec is highly extensible and native to Kubernetes runtime. Check the spec and [What's new in OAM v0.2.0](https://speakerdeck.com/resouer/whats-new-in-oam-v1alpha2-spec) for more detail!|
 |Mar 26th, 2020. A proof-of-concept project named AWS ECS for OAM is published! Check [the AWS Labs repo ](https://github.com/awslabs/amazon-ecs-for-open-application-model) and have fun with developer centric experience with OAM + Fargate!|
 
 Open Application Model is a platform-agnostic specification for building cloud native applications.
@@ -63,15 +68,19 @@ The specification convention adopts [Kubernetes Resource Model](https://github.c
   - [Practical Considerations](8.practical_considerations.md)
   - [Design Principles](9.design_principles.md)
 
+## Versioning
 
-## Community
+Releases of the specification are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [OAM release page](https://github.com/oam-dev/spec/releases). Implementations of the specification are required to specify which version they implement.
 
-### Versioning
+### Changes to the API objects
 
-Since July 2020, changes to the specification are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [its release page](https://github.com/oam-dev/spec/releases). Layout (e.g. repo structure, doc format etc) changes are not versioned. Specific implementations of the specification (e.g. OAM Kubernetes Runtime ) should specify which version they implement.
+Changes to the API objects in this specification follows [on compatibility](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#on-compatibility) and [incompatible api changes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#incompatible-api-changes) defined in Kubernetes API convention. It doesn't couple with release version of the specification.
 
 Changes to the change process (e.g. governance model, review/approve process etc) itself are not currently versioned but may be independently versioned in the future.
 
+
+## Community
+
 ### Milestones
 
 To get an overview of the milestones and their description please visit the [Milestones](https://github.com/oam-dev/spec/milestones) page.