Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Spec 3061 - Marketing Version #3062

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Spec 3061 - Marketing Version #3062

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b448e3f
Write stupid first; First draft of Spec
Trenly Mar 10, 2023
c4c8595
Spelling
Trenly Mar 10, 2023
ff2b1e5
Reference Tab Completion
Trenly Jun 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/actions/spelling/allow.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -594,6 +594,8 @@ toupper
TOutput
towlower
TRACELOGGING
Trenly
trenlymc
triaged
trunc
TRUSTEDPEOPLE
Expand Down
122 changes: 122 additions & 0 deletions doc/specs/#3061 - Marketing Version.md
View file
Open in desktop
Trenly marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
author: Kaleb Luedtke (Trenly) [email protected]
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 <query> --versions` and `winget search <query> --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
Trenly marked this conversation as resolved.
Show resolved Hide resolved
Installers:
InstallerUrl: https://example.com
InstallerSha256: <SHA>
InstallerType: exe
AppsAndFeaturesEntries:
- DisplayVersion: 1.2.5-abcde
...
```

### `winget list`
```
Name Id Version Available
----------------------------------------------------------
Example Package Example.Package 1.2.4 1.2.5
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to confirm, the installed Version here is from arp entry display version and Available version is from marketing version? Would that cause confusion if Available version is way different from installed version?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or were you thinking the installed Version would be mapped to marketing version as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking that installed version would be mapped to marketing version as well. Say for instance the installed version was 1.2.4-a1b2c3Hash the marketing version could be used to show 1.2.4.1 . Where if the installed version was 1.2.4-d1e2f3Hash the marketing version could be used to show 1.2.4.2.

I do realize that this could potentially make correlation on large correlation operations a little slower, but since the correlation is already being performed between installed and available packages, I would presume the impact of an additional mapping would be minor.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is assuming all installed versions are listed in winget repos, which is not the case most of the time. Currently installed to available mapping only happens when the manifest contains DisplayName in Apps and Features entries. If we want to achieve showing marketing version for installed, we need to map installed to available for all cases. And likely, we'll get < SomeMarketVersion as a result most of the time.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm. That's true, but its also not different than what happens currently when there is a DisplayVersion specified and the installed version doesn’t match an available version

Copy link
Contributor

@yao-msft yao-msft Jun 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. We can only do relative version < SomeVersion if the mapping is performed. It's just the question that is showing < SomeMarketVersion is better or < SomePackageVersion is better.

I was thinking to make the logic easier. We only do mapping when ARP DisplayVersion is specified in the manifest, most likely, packages that need marketing version are those packages needing mapping because they write non standard versions in registry.

Copy link
Contributor Author

@Trenly Trenly Jun 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense, and I agree it would be a rarity to use MarketingVersion without DisplayVersion

```

### `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 Example Package [Example.Package] 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 Example Package [Example.Package] 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`