Spec update 1.5: split spec into versioned docs

oam-dev · Sep 2, 2020 · 6c985e0 · 6c985e0
1 parent 1bcb98f
commit 6c985e0
Show file tree

Hide file tree

Showing 3 changed files with 102 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -7,71 +7,63 @@
 
 Open Application Model is a runtime-agnostic specification for modeling cloud native applications and building app-centric platforms.
 
-Focused on application development and operation, _Open Application Model_ brings modular, extensible, and portable design to building application-first platforms on any underlying runtime system such as Kubernetes, cloud, or IoT devices.
+Focused on application development and operation, _Open Application Model_ brings modular, extensible, and portable design for creating application-first platforms on any infrastructures such as Kubernetes, cloud, or IoT devices.
 
-> **NOTICE:** The current working draft of OAM specification (0.2.x release) is under pre-beta release, which means the specification is still under development but will keep backward compatibility in any further change. Interested in contributing? Take a look at the issues! We're looking for more great ideas on how to model cloud native applications.
+> **NOTICE:** The current working draft of OAM specification (0.2.x release) is under pre-beta release, which means the specification is still under development but will keep backward compatibility for any further change.
 
 ## Introduction
 
-Open Application Model provides a series of standard but extensible abstractions to model application in a self-contained approach, which means both the components and corresponding operational capabilities (named "traits") are considered as parts of a given application. This enables platform builders to create platforms around this model, with an app-centric mindset by natural, and essentially changes building platforms into developing components and traits for the application to run. 
+Developers think in terms of application architecture, not of infrastructure.
 
-In addition, categorizing runtime capabilities into modularized components and traits will also provide better discoverability, manageability and interoperability to these capabilities regardless the runtime systems they rely on. 
+In a nutshell, Open Application Model defines standard but extensible abstractions to model applications in a "self-contained" approach, i.e. both runnable components and corresponding operational capabilities (named "traits") are considered as parts of the given application. This enables platform builders to create platforms around this unified model, with app-centric mindset by natural, and essentially changes building platforms into developing modularized components and traits for the application. 
 
 ![How it works][how-it-works]
 
-In one word, Open Application Model empowers application platforms to provide standardized application centric primitives (e.g. Components and Traits) instead of exposing infrastructure details to end users, while retaining the high flexibility and extensibility for platform builders. This model won't lock you into any specific abstractions -- on the contrary, its primitives are designed to allow you to define the right level of abstraction depend on your own use case.
+In addition, Open Application Model won't lock you into any specific abstractions -- on the contrary, its primitives are designed to allow you to define the right level of abstraction depend on your own use case.
 
-Open Application Model specification convention adopts [Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md) which we believe will become the standard interface for the majority of platforms in the future.
+### A team-centric model
 
-### Team-centric personas
+When it comes to the application centric primitives, we think it is important to separate concerns between the parts that developers are responsible for, and the parts that operators and platform engineers are responsible for. 
 
-When it comes to the application centric primitives, we think it is important to distinguish between the parts that developers are responsible for, and the parts that operators (or the platform itself) are responsible for. 
+This is because in practice different levels of abstraction would apply to different personas. Also, if these primitives get muddled in the platform, a simple operational modification on wrong primitive would easily result in bugs, mishaps or even service outages.
 
-This is because in practice different levels of abstraction would apply to different personas. Also, if these primitives get muddled in the platform, a careless operational modification on wrong primitive would easily result in bugs, mishaps or even service outages.
-
-Thus _Open Application Model_ defines different abstractions for different roles responsible for building and operating apps and maintaining infrastructure.
+Thus _Open Application Model_ defines different personas from building and operating apps to maintaining infrastructure.
 
 * _Developers_ are responsible for writing business logic, describing what a microservice or component does,
   and _how_ it can be configured. They are the domain experts on the code.
 * _Application Operators_ are responsible for configuring the runtime aspects of
   one or more of these microservices. They are the domain experts on the
-  platform. In fully automatic use cases (e.g. Serverless), application operator could be the platform itself.
+  platform. In some use cases (e.g. Serverless), application operator could be the platform itself.
 * _Infrastructure Operators_ also known as _Platform Builders_, are responsible for setting up and maintaining the
   infrastructure within which applications run. They are the domain
   experts on developing platform capabilities and infrastructure-level details.
 
 For more details and user stories, see [introduction.md](./introduction.md).
 
-## See it in action
-
-[OAM Kubernetes Runtime](https://github.com/crossplane/oam-kubernetes-runtime) is the officially maintained OAM plugin for Kubernetes, which is a [joint effort](https://cloudblogs.microsoft.com/opensource/2020/05/27/open-application-model-oam-v1alpha2-crossplane/) with [Crossplane](https://github.com/crossplane/crossplane) community. 
+## Read the specification
 
-## The Specification
+The following documents are available:
 
-  - [Notational Conventions](notational_convention.md)
-  - [Purpose and Goals](1.purpose_and_goals.md)
-  - [Overview and Terminology](2.overview_and_terminology.md)
-  - API Resource Specification
-    - Application Developers
-      - [Components](4.component.md)
-    - Application Operators
-      - [Application Scopes](5.application_scopes.md)
-      - [Traits](6.traits.md)
-      - [Application Configuration](7.application_configuration.md)
-    - Infrastructure Operators/Platform Builders
-      - [Workload Definition](3.workload.md)
-  - [Practical Considerations](8.practical_considerations.md)
-  - [Design Principles](9.design_principles.md)
+|                               |         Latest Release             |    Working Draft                           |
+| :---------------------------- | :--------------------------------: | :----------------------------------------: |
+| **Core Specification:**       |
+| OAM Specification             |  [v0.2.1](https://github.com/oam-dev/spec/blob/v0.2.1/SPEC_LATEST_STABLE.md) |  [v0.2.2-WD](https://github.com/oam-dev/spec/blob/master/SPEC_WORKING_DRAFT.md)  |
+|                               |
+| **Workloads**  |
+| Containerized Workload  |  [v1alpha2](https://github.com/oam-dev/spec/blob/v0.2.1/core/workloads/containerized_workload/containerized_workload.md)  |  [v1alpha2-WD](https://github.com/oam-dev/spec/blob/master/core/workloads/containerized_workload/containerized_workload.md)          |
+|                               |
+| **Traits**  |
+| Manual Scaler  |  [v1alpha2](https://github.com/oam-dev/spec/blob/v0.2.1/core/traits/manual_scaler_trait.md)  |  [v1alpha2-WD](https://github.com/oam-dev/spec/blob/master/core/traits/manual_scaler_trait.md)          |
+|                               |
+| **Scopes**  |
+| Network Scope  |  [v1alpha2](https://github.com/oam-dev/spec/blob/v0.2.1/standard/scopes/network_scope.md)  |  [v1alpha2-WD](https://github.com/oam-dev/spec/blob/master/standard/scopes/network_scope.md)          |
+| Health Scope  |  [v1alpha2](https://github.com/oam-dev/spec/blob/v0.2.1/standard/scopes/health_scope.md)  |  [v1alpha2-WD](https://github.com/oam-dev/spec/blob/master/standard/scopes/health_scope.md)          |
 
-## Versioning
 
-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.
 
-### Changes to the API objects
-
-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.
+## See it in action
 
-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.
+[OAM Kubernetes Runtime](https://github.com/crossplane/oam-kubernetes-runtime) is the officially maintained OAM plugin for Kubernetes. This is a [joint effort](https://cloudblogs.microsoft.com/opensource/2020/05/27/open-application-model-oam-v1alpha2-crossplane/) with [Crossplane](https://github.com/crossplane/crossplane) community. 
 
 
 ## Community
@@ -102,6 +94,8 @@ One of the easiest ways to contribute is to participate in discussions. There ar
 | IM Channel      | https://gitter.im/oam-dev/ |
 | Twitter      | [@oam_dev](https://twitter.com/oam_dev) |
 
+[how-it-works]: assets/how-it-works.png
+
 ### Resources
 
 Come find community blogs and conference talks about OAM in [community/talks_and_blogs.md](./community/talks_and_blogs.md).
diff --git a/SPEC_LATEST_STABLE.md b/SPEC_LATEST_STABLE.md
@@ -0,0 +1,36 @@
+
+# Open Application Model
+
+## Version
+
+This is OAM **spec** version **v0.2.1**.
+Learn more about versioning [below](#versioning).
+
+## The Specification
+
+  - [Notational Conventions](notational_convention.md)
+  - [Purpose and Goals](1.purpose_and_goals.md)
+  - [Overview and Terminology](2.overview_and_terminology.md)
+  - API Resource Specification
+    - Application Developers
+      - [Components](4.component.md)
+    - Application Operators
+      - [Application Scopes](5.application_scopes.md)
+      - [Traits](6.traits.md)
+      - [Application Configuration](7.application_configuration.md)
+    - Infrastructure Operators/Platform Builders
+      - [Workload Definition](3.workload.md)
+  - [Practical Considerations](8.practical_considerations.md)
+  - [Design Principles](9.design_principles.md)
+
+## Versioning
+
+Open Application Model specification convention adopts [Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md) which we believe will become the standard interface for the majority of platforms in the future.
+
+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.
+
+### Changes to the API objects
+
+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.
diff --git a/SPEC_WORKING_DRAFT.md b/SPEC_WORKING_DRAFT.md
@@ -0,0 +1,36 @@
+
+# Open Application Model
+
+## Version
+
+This is OAM **spec** working draft version **v0.2.2-WD**.
+Learn more about versioning [below](#versioning).
+
+## The Specification
+
+  - [Notational Conventions](notational_convention.md)
+  - [Purpose and Goals](1.purpose_and_goals.md)
+  - [Overview and Terminology](2.overview_and_terminology.md)
+  - API Resource Specification
+    - Application Developers
+      - [Components](4.component.md)
+    - Application Operators
+      - [Application Scopes](5.application_scopes.md)
+      - [Traits](6.traits.md)
+      - [Application Configuration](7.application_configuration.md)
+    - Infrastructure Operators/Platform Builders
+      - [Workload Definition](3.workload.md)
+  - [Practical Considerations](8.practical_considerations.md)
+  - [Design Principles](9.design_principles.md)
+
+## Versioning
+
+Open Application Model specification convention adopts [Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md) which we believe will become the standard interface for the majority of platforms in the future.
+
+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.
+
+### Changes to the API objects
+
+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.