MS-8916: Update EQP API DevDocs per customer's experience

 - added required field when creating a new package: "version"
 - added conditionally required field when creating a new package: "sku"

Author: Mike Weis

src/marketplace/eqp/v1/packages.md

@@ -108,7 +108,7 @@ Both `POST` and `PUT` requests support a batch model where multiple packages can
 |shared_packages[N].artifact.sku|string|GET, POST, PUT|both|no|The shared package file|Unique file upload ID obtained from the Files API.|
 |shared_packages[N].artifact.version|string|GET, POST, PUT|both|no|The shared package file|Unique file upload ID obtained from the Files API.|
 |short_description|substring|GET, POST, PUT|marketing|yes|The short description for the package.|Short free text|
-|sku|substring|GET|-|yes|The SKU generated from metadata in the code artifact.|A SKU|
+|sku|substring|GET, POST|-|yes|The SKU generated from metadata in the code artifact. Only specified in a `POST` when creating another version of an existing extension.|A SKU|
 |stability|string|GET, POST, PUT|marketing|yes|The version's build stability|`stable`, `beta`|
 |sort|string|GET|-|no|A comma-separated list of fields to sort the list, each field prefixed by `-` for descending order, or `+` for ascending order.|See [Get package details](#get-package-details).|
 |submission_id|substring|GET, PUT|-|yes|A globally unique ID assigned to a package when it is submitted in a POST request. All further references to this package using GET or PUT requests can be made supplying this identifier.|A generated string|
@@ -124,7 +124,7 @@ Both `POST` and `PUT` requests support a batch model where multiple packages can
 |version_compatibility|array|GET, POST, PUT|technical|no|List of Magento versions that this package supports. Must match the editions in `prices`|Array of objects|
 |version_compatibility[N].edition|string|GET, POST, PUT|technical|no|Magento edition for the accompanying versions list|`M2`|
 |version_compatibility[N].versions|array|GET, POST, PUT|technical|no|List of Magento versions that this package supports in the given edition.|Array of version strings, eg ["2.3","2.4"]
-|version|substring|GET|-|yes|The version of this package.|`major.minor.patch`, eg `2.5.3`.|
+|version|substring|GET, POST|both|yes|The version of this package.|`major.minor.patch`, eg `2.5.3`.|
 
 ### Additional notes
 
@@ -515,8 +515,9 @@ Send the "submit" action for the marketing content to re-publish the product.
 }
 ```
 
-*  The *overall* value indicates where the package is in the EQP pipeline.
-*  Additional details are provided in the two main EQP areas:
+* This is a read-only field. 
+* The **overall** value indicates where the package is in the EQP pipeline.
+* Additional details are provided in the two main EQP areas:
    *  **technical** - Provides the current technical status.
    *  **marketing** - Provides the current marketing status.
 
@@ -569,8 +570,9 @@ PUT /rest/v1/products/packages/:item_id
 
 You can submit a package in either of the following ways:
 
-*  A single POST request with all required fields set. You must explicitly indicate that you are submitting for technical and marketing review using the `action` parameter.
-*  A series of requests, typically in the following order:
+* A single POST request with all required fields set. You must explicitly indicate that you are submitting for technical and marketing review using the `action` parameter.
+  *  If this package represents a newer version to an already existing extension, then also supply the `sku` parameter.
+* A series of requests, typically in the following order:
    1. A single POST request with the minimum required fields set and `action` set to `draft` in either `technical`, `marketing`, or both. This request accepts the new package and saves it on the Developer Portal for further updates. It returns a unique `submission_id` for subsequent PUT operations.
    1. One or more PUT requests in which you configure the package parameters. In these requests, set `action` to `draft` in `technical`, `marketing`, or both.
    1. A final PUT request indicating submission for `technical`, `marketing`, or both.
@@ -613,7 +615,8 @@ The following example shows a POST request with all required parameters set for
     "name" : "One Click Checkout",
     "short_description" : "<Short description here>",
     "long_description" : "<Long description here>",
-    "release_notes" : "<Release notes here>",
+    "release_notes" : "<Release notes here>", 
+    "version" : "1.1.5",
     "artifact" : {
       "file_upload_id" : "5c11e656057b42.97931218.5"
     },
@@ -733,13 +736,13 @@ curl -X POST \
 
 The PUT method can be used to update packages in the following states:
 
-*  The package is in draft mode for the technical or marketing review; or both.
-*  The package has been rejected in either the technical or marketing review; or both.
+* The package is in draft mode for the technical or marketing review; or both.
+* The package has been rejected in either the technical or marketing review; or both.
    You must fix these issues and re-submit the package.
-*  The package has been released to the Commerce Marketplace.
-*  The package was removed from Commerce Marketplace by the developer and needs to be re-published.
-*  The package can be recalled while in the EQP pipeline.
-*  After a package has been released to the Commerce Marketplace, you can update marketing information only.
+* The package has been released to the Commerce Marketplace.
+* The package was removed from Commerce Marketplace by the developer and needs to be re-published.
+* The package can be recalled while in the EQP pipeline.
+* After a package has been released to the Commerce Marketplace, you can update marketing information only.
    Changing marketing information causes the package to be placed in marketing review.
    The package continues to be live on the marketplace, and after the marketing approval,
    the updated fields will be published to the store.
@@ -765,7 +768,7 @@ The HTTP response code will indicate success or failure.
 
 #### Required parameters
 
-If the **action** parameter gives a `submit` value for technical, marketing or both,
+If the **action** parameter gives a `submit` value for **technical**, **marketing** or both,
 the required parameters are listed below by their respective parallel EQP pipelines:
 
 ##### Technical
@@ -776,6 +779,8 @@ the required parameters are listed below by their respective parallel EQP pipeli
 |platform||
 |version_compatibility||
 |release_notes||
+|version||
+|sku|only valid when a previous version exists|
 |artifact||
 |documentation_artifacts|At least the `user` guide must be supplied.|
 
@@ -796,14 +801,16 @@ the required parameters are listed below by their respective parallel EQP pipeli
 
 ##### Submission in several steps
 
-As described earlier, a submission can also be done in several steps in draft mode, followed by the action to `submit` for technical and/or `marketing` review. In such cases, the first
+As described earlier, a submission can also be done in several steps in draft mode, followed by the action to `submit` for **technical** and/or **marketing** review. In such cases, the first
 POST request in draft mode can be done with a minimal set of parameters:
 
 |Parameter|Comments|
 |---------|--------|
 |type|
 |platform|
 |name||
+|version||
+|sku|only valid when a previous version exists|
 |short_description||
 |long_description||