Fix Additional Metadata for App Submission packages #70

HowardWolosky · 2017-10-13T21:12:40Z

In v1.6.0, we added additional metadata
to the generated JSON file for application submission packages.

Unfortunately, we operated under the incorrect assumption that there could
only ever be a single Min OS version specified for a package. In fact, a
single package can target multiple device families, and each device family
can target a different minimum OS version. The only requirement around
Min OS Versions for packages is that if there is an appxbundle, all appx
files within that bundle must target the same minimum os version for a given
device family.

Given this change in our understanding of how things work, we're modifying
the additional metadata that we were generating. targetDeviceFamiliesEx
will now contain the same version that targetDeviceFamilies contains
(both the device family name and the minimum os version), but they will
be split into named properties. Additionally, the minOsVersion property
has been removed since the data it has is less relevant when it's not paired
with the specific deviceFamily that it's related to.

Finally, we are now adding a new sbschema property (which is simply an
integer) which we'll be increasing from now on whenever we make changes
to non-standard properties in our output JSON in the event that StoreBroker
(or other applications leveraging the StoreBroker payload) are depending on
those values and need to know how to behave if they're not there.

USAGE.md has been updated to now track (and explain) the
schema version changes
(for botn App submissions and for IAP submissions).

danbelcher-MSFT · 2017-10-18T18:40:23Z

StoreBroker/PackageTool.ps1

-        $metadata.targetDeviceFamiliesEx += $manifest.Package.Dependencies.TargetDeviceFamily.Name |
-            Where-Object { $null -ne $_ } |
-            Sort-Object -Unique
+        $metadata.targetDeviceFamiliesEx += $manifest.Package.Dependencies.TargetDeviceFamily |


I generally just wrap the pipeline with @() to keep this as one line. Up to you.

Fine with leaving this as-is for now, given that this current pattern is used elsewhere in even this method, so I'd prefer consistency in this case (and I'd rather not make unrelated changes within the context of this PR).

danbelcher-MSFT · 2017-10-18T18:43:00Z

StoreBroker/PackageTool.ps1

-                targetPlatform       = $appxMetadata.targetPlatform;
+                version                = $appxMetadata.version;
+                targetDeviceFamiliesEx = $appxMetadata.targetDeviceFamiliesEx
+                targetDeviceFamilies   = $appxMetadata.targetDeviceFamiliesEx | ForEach-Object { "$($_.name) min version $($_.minOSVersion)" }


The "{0} min version {1}" string is duplicated here and above. Worth making a constant? Or worth making a function to return the formatted string?

Yep. Good idea.

danbelcher-MSFT · 2017-10-18T18:49:37Z

Documentation/USAGE.md

+## Schema Versions
+
+StoreBroker's packaging commands (`New-SubmissionPackage` and `New-InAppProductSubmissionPackage`)
+add proprties to the generated .json file that are not part of the official Submission API JSON


typo: "properties"

danbelcher-MSFT · 2017-10-18T18:50:36Z

StoreBroker/PackageTool.ps1

+# we alter what additional metadata is added to the schema for that submission type.
+$script:appSchemaVersion = 2;
+$script:iapSchemaVersion = 2;
+$script:schemaPropertyName = 'sbschema'


camel-case? 'sbSchema'

Sure. Done.

danbelcher-MSFT · 2017-10-18T18:54:36Z

Documentation/USAGE.md

+
+### App Submission Packages
+
+#### 1


I'd prefer 'Version 1' explicitly. Having just '1' looks odd in the rendered markdown.

The reason that I had done that was so that it mapped to the literal value that the property would have. I agree that it looked weird though. I've added the word Version before the 1 and 2 and I bolded the integer value note above that area indicating what the actual value of the sbschema could be.

danbelcher-MSFT · 2017-10-18T18:54:51Z

Documentation/USAGE.md

+
+#### 1
+
+> We never used the value `1` for a published schema.  Any App JSON package file that doesn't have an


I think this is okay as regular text and not as a note. Ver 2 has regular text here. On GitHub, the note uses gray font color and is actually harder to read than regular text.

danbelcher-MSFT · 2017-10-18T18:58:52Z

StoreBroker/PackageTool.ps1

+# The StoreBroker schema may include metadata that isn't a core part of the official Submission API
+# JSON schema (like the appId or iapId, package metadata, etc...). These values should be updated any time
+# we alter what additional metadata is added to the schema for that submission type.
+$script:appSchemaVersion = 2;


nit: don't need the semi-colons

Not sure how that slipped in there.

danbelcher-MSFT · 2017-10-18T18:59:30Z

StoreBroker/PackageTool.ps1

+# The StoreBroker schema may include metadata that isn't a core part of the official Submission API
+# JSON schema (like the appId or iapId, package metadata, etc...). These values should be updated any time
+# we alter what additional metadata is added to the schema for that submission type.
+$script:appSchemaVersion = 2;


Maybe we should define these in Helpers.ps1? Or other shared file? We don't have a need to reference these elsewhere right now but they also aren't necessarily only useful for PackageTool

It's a good thought. These are accessible to any of the other scripts. I don't want to put them in Helpers. My general hope for Helpers.ps1 is that it eventually goes away and those generic methods come from some other shared project.

I'd much rather that these "constants" be defined and live close to the code that is using them at its core (in this case, PackageTool).

In v1.6.0, we added [additional metadata](microsoft@391954b) to the generated JSON file for application submission packages. Unfortunately, we operated under the incorrect assumption that there could only ever be a single Min OS version specified for a package. In fact, a single package can target multiple device families, and each device family can target a different minimum OS version. The only requirement around Min OS Versions for packages is that if there is an appxbundle, all appx files within that bundle must target the same minimum os version for a given device family. Given this change in our understanding of how things work, we're modifying the additional metadata that we were generating. `targetDeviceFamiliesEx` will now contain the same version that `targetDeviceFamilies` contains (both the device family name and the minimum os version), but they will be split into named properties. Additionally, the `minOsVersion` property has been removed since the data it has is less relevant when it's not paired with the specific deviceFamily that it's related to. Finally, we are now adding a new `sbschema` property (which is simply an integer) which we'll be increasing from now on whenever we make changes to non-standard properties in our output JSON in the event that StoreBroker (or other applications leveraging the StoreBroker payload) are depending on those values and need to know how to behave if they're not there. USAGE.md has been updated to now track (and explain) the [schema version changes](https://github.com/Microsoft/StoreBroker/blob/master/Documentation/USAGE.md#schema-versions) (for botn App submissions and for IAP submissions).

HowardWolosky requested a review from danbelcher-MSFT October 13, 2017 21:12

danbelcher-MSFT reviewed Oct 18, 2017

View reviewed changes

danbelcher-MSFT approved these changes Oct 18, 2017

View reviewed changes

HowardWolosky force-pushed the schemaProperties branch from f3666c1 to 5480643 Compare October 24, 2017 21:33

HowardWolosky merged commit c8b643c into microsoft:master Oct 24, 2017

HowardWolosky deleted the schemaProperties branch October 24, 2017 21:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix Additional Metadata for App Submission packages #70

Fix Additional Metadata for App Submission packages #70

HowardWolosky commented Oct 13, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017

danbelcher-MSFT Oct 18, 2017

HowardWolosky Oct 24, 2017


		#### 1

		> We never used the value `1` for a published schema. Any App JSON package file that doesn't have an

Fix Additional Metadata for App Submission packages #70

Fix Additional Metadata for App Submission packages #70

Conversation

HowardWolosky commented Oct 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment