From b448e3fa8af93a68091b5f0f93b8bb144172d93f Mon Sep 17 00:00:00 2001 From: Kaleb Luedtke Date: Fri, 10 Mar 2023 13:54:18 -0600 Subject: [PATCH 1/3] Write stupid first; First draft of Spec --- doc/specs/#3061 - Marketing Version.md | 122 +++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 doc/specs/#3061 - Marketing Version.md diff --git a/doc/specs/#3061 - Marketing Version.md b/doc/specs/#3061 - Marketing Version.md new file mode 100644 index 0000000000..f5f175d989 --- /dev/null +++ b/doc/specs/#3061 - Marketing Version.md @@ -0,0 +1,122 @@ +--- +author: Kaleb Luedtke (Trenly) trenlymc@gmail.com +created on: 2023-03-10 +last updated: 2023-03-10 +issue id: 3061 +--- + +# Marketing Version + +"For [#3061](https://github.com/microsoft/winget-cli/issues/3061)" + +## Abstract + +There are times when the version which is marketed to consumers on publishers' websites differs from what is written to the Apps and Features Entries data. Additionally, there are times when the same version is marketed for several different versions of the same package. The Windows Package Manager should be able to show an arbitrary version as determined by the publisher. + +## Inspiration + +The current design using `PackageVersion` for the displayed version and how it differs from `DisplayVersion` can be confusing. + +## Solution Design + +The Windows Package Manager manifest schema should have a `MarketingVersion` key added at the root level. For clarity, it should be placed immediately following the `PackageVersion` key. + +When the Windows Package Manager needs to display the version of a package, the value from the `MarketingVersion` key should be used. If the key is not present or has no value, the value of `PackageVersion` should be displayed instead, with the exception of `winget show --versions` and `winget search --versions` which should show the values as key pairs of `PackageVersion (MarketingVersion)`. + +When the `--version` parameter is used, matches with `PackageVersion` should be considered first and matches with `MarketingVersion` should be considered second. If there are multiple package versions of the same identifier matched using `MarketingVersion`, the highest `PackageVersion` shall be selected. + +When `MarketingVersion` is present, `PackageVersion` should be validated to be a semantic version. + +For the purposes of version comparison, mapping installed packages to versions, and all other behaviors, the current implementation using `PackageVersion` should be retained. + +## UI/UX Design + +Example of a manifest with a `MarketingVersion` specified: +```yaml +PackageIdentifier: Example.Package +PackageVersion: 1.2.5.1 +MarketingVersion: 1.2.5 +Installers: + InstallerUrl: https://example.com + InstallerSha256: + InstallerType: exe + AppsAndFeaturesEntries: + - DisplayVersion: 1.2.5-abcde +... +``` + +### `winget list` +``` +Name Id Version Available +---------------------------------------------------------- +Example Package Example.Package 1.2.4 1.2.5 +``` + +### `winget show Example.Package --versions` +``` +Found Example Package [Example.Package] +Version +------------- +1.2.5.1 (1.2.5) +1.2.4.9 (1.2.4) +1.2.4.8b (1.2.4 beta) +1.2.4.7b (1.2.4 beta) +``` + +### `winget upgrade` when the installed version and newer version have the same marketing version +``` +Name Id Version Available Source +-------------------------------------------------------------------- +Example Package Example.Package 1.2.5 * 1.2.5 winget +``` + +### `winget install Example.Package --version 1.2.4.7b` +*This would install version 1.2.4.7b* +``` +Found Badlion Client [Badlion.BadlionClient] Version 1.2.4 beta +This application is licensed to you by its owner. +... +``` + +### `winget install Example.Package --version '1.2.4 beta'` +*This would install version 1.2.4.8b* +``` +Found Badlion Client [Badlion.BadlionClient] Version 1.2.4 beta +This application is licensed to you by its owner. +... +``` + +## Capabilities +Installed packages should still be mapped to `PackageVersion`, which will allow winget to update packages which change `DisplayVersion` but do not change `MarketingVersion`. + +`MarketingVersion` will allow for packages which use non-semantic versions to have a semantic `PackageVersion` while retaining the non-semantic mapping for `DisplayVersion` and consumer-facing version messages. + +### Accessibility + +The Windows Package Manager has been built in such a way that screen readers will still provide audible output as the command is executed keeping the user informed of progress, warnings, and errors. This should have no direct impact on accessibility. + +### Security + +There should be no security impact. + +### Reliability + +This change will require exposing the marketing version as part of the pre-indexed package and REST source. However, the reliability of the publishing pipelines is not anticipated to be affected. + +### Compatibility + +Marketing Versions will be an extension to the current version framework, so no compatibility issues are expected to occur as a result. + +This change will require exposing the marketing version as part of the pre-indexed package and REST source. Older versions of the client may not know how to handle this field + +### Performance, Power, and Efficiency + +The amount of computation required to display the arbitrary value of a text key should have little impact on the current performance of the Windows Package Manager + +## Potential Issues + +* There could be confusion around how to specify a version when using commands. + +## Future considerations + +* Logging the latest installed `PackageVersion` in the `installed.db` may allow for the updating of packages that don't change `DisplayVersion` but do change `MarketingVersion` \ No newline at end of file From c4c8595e857183a653b349b069556879eb0bff42 Mon Sep 17 00:00:00 2001 From: Kaleb Luedtke Date: Fri, 10 Mar 2023 14:04:45 -0600 Subject: [PATCH 2/3] Spelling --- .github/actions/spelling/allow.txt | 2 ++ doc/specs/#3061 - Marketing Version.md | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt index 971d491ee5..84fac42e03 100644 --- a/.github/actions/spelling/allow.txt +++ b/.github/actions/spelling/allow.txt @@ -594,6 +594,8 @@ toupper TOutput towlower TRACELOGGING +Trenly +trenlymc triaged trunc TRUSTEDPEOPLE diff --git a/doc/specs/#3061 - Marketing Version.md b/doc/specs/#3061 - Marketing Version.md index f5f175d989..95dc777f87 100644 --- a/doc/specs/#3061 - Marketing Version.md +++ b/doc/specs/#3061 - Marketing Version.md @@ -73,7 +73,7 @@ Example Package Example.Package 1.2.5 * 1.2.5 winget ### `winget install Example.Package --version 1.2.4.7b` *This would install version 1.2.4.7b* ``` -Found Badlion Client [Badlion.BadlionClient] Version 1.2.4 beta +Found Example Package [Example.Package] Version 1.2.4 beta This application is licensed to you by its owner. ... ``` @@ -81,7 +81,7 @@ This application is licensed to you by its owner. ### `winget install Example.Package --version '1.2.4 beta'` *This would install version 1.2.4.8b* ``` -Found Badlion Client [Badlion.BadlionClient] Version 1.2.4 beta +Found Example Package [Example.Package] Version 1.2.4 beta This application is licensed to you by its owner. ... ``` From ff2b1e5534a724f26825afed6a8fdc2e41241dd3 Mon Sep 17 00:00:00 2001 From: Kaleb Luedtke Date: Thu, 1 Jun 2023 15:27:37 -0500 Subject: [PATCH 3/3] Reference Tab Completion --- doc/specs/#3061 - Marketing Version.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/specs/#3061 - Marketing Version.md b/doc/specs/#3061 - Marketing Version.md index 95dc777f87..b2ecf8dfaa 100644 --- a/doc/specs/#3061 - Marketing Version.md +++ b/doc/specs/#3061 - Marketing Version.md @@ -91,6 +91,8 @@ Installed packages should still be mapped to `PackageVersion`, which will allow `MarketingVersion` will allow for packages which use non-semantic versions to have a semantic `PackageVersion` while retaining the non-semantic mapping for `DisplayVersion` and consumer-facing version messages. +Tab Completion should continue to reference the Package Version. + ### Accessibility The Windows Package Manager has been built in such a way that screen readers will still provide audible output as the command is executed keeping the user informed of progress, warnings, and errors. This should have no direct impact on accessibility.