address feedback

Signed-off-by: Alay Patel <[email protected]>

design-proposals/api-review.md

@@ -1,21 +1,21 @@
 # Overview
-This proposal outlines the establishment of an API review process within kubevirt project. The primary objective of this
+This proposal outlines the establishment of an API review process within KubeVirt project. The primary objective of this
 process is to ensure the quality, consistency, and usability of the project's APIs, enabling developers to effectively
 interact with our software. By implementing an API review process, the aim is to enhance the project's overall
 development experience, encourage collaboration, and foster community engagement.
 
 Kubernetes core APIs have been very successful in maintaining strong backward compatibility along with good usability
 over the years. This proposal uses the Kubernetes api review process as a guide for implementing a similar process for
-kubevirt.
+KubeVirt.
 
 
 ## Motivation
-Since kubevirt is reaching v1 soon and has already had some APIs with v1 version, implementing an API review process
+Since KubeVirt is reaching v1 soon and has already had some APIs with v1 version, implementing an API review process
 ensures code quality, usability, stability, and fosters community collaboration, ultimately leading to a successful and
 sustainable software ecosystem.  
 
 More importantly, it allows for a common framework through which all stake-holders can discuss and decide API facing 
-changes in kubevirt.
+changes in KubeVirt.
 
 ## Goals
 
@@ -33,12 +33,12 @@ changes in kubevirt.
 - Contributors
 
 ## User Stories
-- As a user of kubevirt project, how can I feel confident that kubevirt maintains an intuitive, stable and crisp API that
-  can be used as a foundational block to build products and projects.
-- As a contributor, how do I know the right way to approach API facing change?
-- As a contributor, how do I know get feedback about an API facing change?
-- As a reviewer, what are the list of checks needed for approving an API facing change?
-- As a reviewer, what tools could be used to make api reviews easier and reliable?
+- As a user of KubeVirt project, I want to feel confident that KubeVirt maintains an intuitive, stable and API that can 
+   be used as a foundational block to build products and projects
+- As a contributor, I need guidance on the right way to approach API facing change. Ideally this guidance should include
+    all the steps design docs, contributing the change and post contribution steps
+- As a reviewer, I need to have a compressive list of checks needed for approving an API facing change
+- As a reviewer, ideally, I need to be able to leverage automation wherever possible to make reviewing easier
 
 ## Repos
 - https://github.com/kubevirt/kubevirt
@@ -48,19 +48,24 @@ changes in kubevirt.
 In order to achieve the stability, quality and consistency of APIs like the core Kubernetes APIs this document proposes
 the following changes:
 
-- Process for api reviewers: Process changes to add more resources and visibility for api reviews
-- Process for contributors: Documenting and sharing a guide for adding api facing changes to kubevirt
+- For api reviewers: There should be a one or more engineers that review api breaking changes on a regular basis.
+- For contributors: There should be a guide explaining how to merge and api change
 - Tools and tests: Tools and automation that can be helpful to reduce human burden and errors to carry-out api changes
 
+More details on each of the aforementioned items is highlighted below in separate sections.
+
 ## Process for api reviewers
 Recent changes to reviewer guidelines recommend forming small groups in specific areas of expertise. sig-api-reviews is 
 one such group. This group will be responsible for:
 - Reviewing all the PRs with `kind/api-change` labels
 - Maintaining a high quality, stable and crisp api surface that is backward compatible
 
+The focus of this group should be to lay out the guidelines of an intuitive, maintainable and usable set of APIs for
+KubeVirt project. 
+
 ### How to achieve this?
 
-Kubernetes has a very well-defined process for api-reviews. Taking an inspiration from that kubevirt should have the 
+Kubernetes has a very well-defined process for api-reviews. Taking an inspiration from that, KubeVirt should have the 
 following:
 
 - A specific community call for sig-api-reviewer
@@ -69,7 +74,7 @@ following:
   - can the API changes be better?
   - Any other communication that is needed for contributor to move forward.
 - While goal of the project is to prohibit introducing API breaking changes, automation tools proposed in the Tools section
-  will help in attaining this goal. However some APIs have reached v1 (GA) without any such tool. Hence a well-defined 
+  will help in attaining this goal. However, some APIs have reached v1 (GA) without any such tool. Hence, a well-defined 
   process is needed to address breaking changes discovered in previous versions:
   - If a break in API is reported, the next release:
     - will introduce the fix
@@ -97,11 +102,11 @@ serialized to and from JSON when clients interact with API server. The testing f
 make sure that APIs continue to be serializable upon upgrades
 
 ### Tool to test serialization upon upgrade
-Here is a [demo](https://github.com/alaypatel07/kubevirt-api-fuzzer) tool that identifies api breakages while reading 
+Here is a [demo](https://github.com/alaypatel07/KubeVirt-api-fuzzer) tool that identifies api breakages while reading 
 older objects using newer clients. 
 
 ##### Description and Usage
-1. This tool creates JSON and YAML files for all the API exposed by kubevirt in group-version "kubevirt.io/v1",
+1. This tool creates JSON and YAML files for all the API exposed by KubeVirt in group-version "kubevirt.io/v1",
    versioned by the release. The current version is in `HEAD` directory, previous versions are in `release-0.yy` release
    directory. The following APIs are included, more APIs can be added in the future:
     ```
@@ -128,7 +133,7 @@ older objects using newer clients.
    
 ##### How will it help?
 
-During KubeVirt upgrade, the apiserver is updated last, i.e. for a moment in time until the upgrade rolls out, kubevirt
+During KubeVirt upgrade, the apiserver is updated last, i.e. for a moment in time until the upgrade rolls out, KubeVirt
 components like virt-handler, virt-controller will have newer client, but apiserver will be serving older objects.
 
 Using this tests, it can be asserted that the current newer clients can roundtrip (serialized and de-serialized) past