Skip to content

Commit

Permalink
Resolve dead links (microsoft#199841)
Browse files Browse the repository at this point in the history
Co-authored-by: G.Reijn <[email protected]>
  • Loading branch information
Gijsreyn and G.Reijn authored Dec 19, 2024
1 parent ec52aaa commit 509f52b
Show file tree
Hide file tree
Showing 25 changed files with 48 additions and 31 deletions.
9 changes: 5 additions & 4 deletions doc/Authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ First, we want to say thank you. Your contribution is highly valued. And we appr

### What is a manifest?

Manifests are the YAML files in this repository containing the metadata used by the Windows Package Manager to install and upgrade software on Windows 10. There are thousands of these files partitioned under the [manifests](/manifests) directory. We've had to partition the directory structure so you don't have to scroll as much in the GitHub.com site when you are looking for a manifest.
Manifests are the YAML files in this repository containing the metadata used by the Windows Package Manager to install and upgrade software on Windows 10. There are thousands of these files partitioned under the [manifests](../manifests/) directory. We've had to partition the directory structure so you don't have to scroll as much in the GitHub.com site when you are looking for a manifest.

### What is a package?

Expand Down Expand Up @@ -41,9 +41,10 @@ Manifests submitted to the Windows Package Manager Community Repository should b

## Creating your first manifest

Once you have a package in mind that doesn't already exist in the repository, you can now start [creating your package manifest](https://docs.microsoft.com/en-us/windows/package-manager/package/manifest?tabs=minschema%2Cversion-example). We recommend using the [Windows Package Manager Manifest Creator (a.k.a Winget-Create)](https://github.com/microsoft/winget-create) to help you generate your manifest. Winget-Create is a command line tool that will prompt you for relevant metadata related to your package. Once you are done, Winget-Create will validate your manifest to verify that it is correct and allow you to submit your newly-created manifest directly to the winget-pkgs repository by linking your GitHub account. Alternatively, you can use the [YamlCreate.ps1 Script](/Tools/YamlCreate.ps1). More information on using YamlCreate is found in the [script documentation](tools/YamlCreate.md).
Once you have a package in mind that doesn't already exist in the repository, you can now start [creating your package manifest](https://docs.microsoft.com/en-us/windows/package-manager/package/manifest?tabs=minschema%2Cversion-example). We recommend using the [Windows Package Manager Manifest Creator (a.k.a Winget-Create)](https://github.com/microsoft/winget-create) to help you generate your manifest. Winget-Create is a command line tool that will prompt you for relevant metadata related to your package. Once you are done, Winget-Create will validate your manifest to verify that it is correct and allow you to submit your newly-created manifest directly to the winget-pkgs repository by linking your GitHub account. Alternatively, you can use the [YamlCreate.ps1 Script](../Tools/YamlCreate.ps1). More information on using YamlCreate is found in the [script documentation](tools/YamlCreate.md).

## Installer Architectures

If you are authoring a manifest yourself one of the important things to note related to installer types is architecture. In many cases the installer itself may be an x86 installer, but it will actually install the package for the architecture of the system. In these cases, the installer type in the manifest should indicate the architecture of the installed binaries. So in some cases the actual installer itself targets x86, but in fact it will install an x64 version of the package.


Expand Down Expand Up @@ -114,13 +115,13 @@ There are a few typical use cases when `AppsAndFeaturesEntries` should be specif

There are many ways that publishers choose to version their software. This leads to some cases where the way WinGet sorts versions will not work properly. Some examples include packages that only use commit hashes for their releases, packages which prefix the version number with a string, or packages using date versioning of DD-MM-YYYY.

When this happens, `PackageVersion` should be set to something which is sortable by WinGet and `DisplayVersion` should be set to the value the installer writes to the registry. For more information, see the section on [Version Sorting in WinGet](/doc/Authoring.md#version-sorting-in-winget)
When this happens, `PackageVersion` should be set to something which is sortable by WinGet and `DisplayVersion` should be set to the value the installer writes to the registry. For more information, see the section on [Version Sorting in WinGet](../doc/Authoring.md#version-sorting-in-winget)

4. The `InstallerType` of the installer which writes the registry keys does not match the `InstallerType` of the manifest

In some cases an EXE installer may call an embedded MSI which writes data to the registry in a different format. While the `InstallerType` may be correctly identified in the manifest, the WinGet CLI will detect the registry entries as being from an MSI and return an error that the installation technology does not match when running `winget upgrade`. This requires the `InstallerType` to be specified in `AppsAndFeaturesEntries`

For more information on how to specify `AppsAndFeaturesEntries` and what the available metadata fields are, please see the [Manifest Specification](/doc/manifest).
For more information on how to specify `AppsAndFeaturesEntries` and what the available metadata fields are, please see the [Manifest Specification](../doc/manifest/).

## Version Sorting in WinGet

Expand Down
6 changes: 3 additions & 3 deletions doc/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ Getting started is the hard part. There are several tools which we recommend for

First is the [Windows Package Manager Manifest Creator (a.k.a Winget-Create)](https://github.com/microsoft/winget-create). Winget-Create is a command line tool that will prompt you for relevant metadata related to your package. Once you are done, Winget-Create will validate your manifest to verify that it is correct and allow you to submit your newly-created manifest directly to the winget-pkgs repository by linking your GitHub account.

Second is the [YamlCreate PowerShell Script](/Tools/YamlCreate.ps1). This tool is great for those who are technically inclined and understand the basics of forking, cloning, and commits. YamlCreate iterates much faster than Winget-Create but has largely the same functionality. More information on YamlCreate can be found in the [Script Documentation](tools/YamlCreate.md).
Second is the [YamlCreate PowerShell Script](../Tools/YamlCreate.ps1). This tool is great for those who are technically inclined and understand the basics of forking, cloning, and commits. YamlCreate iterates much faster than Winget-Create but has largely the same functionality. More information on YamlCreate can be found in the [Script Documentation](tools/YamlCreate.md).

Need more information? Take a look at the document on [Authoring Manifests](Authoring.md) and the [Microsoft Documentation Site](https://docs.microsoft.com/windows/package-manager/package/manifest).
## **How do I get the AppsAndFeaturesEntries for an installer?**
The best way to get the AppsAndFeaturesEntries, or the ARP Entries, for an installer is to run the installer inside of the [Windows Sandbox](https://docs.microsoft.com/windows/security/threat-protection/windows-sandbox/windows-sandbox-overview). Instructions on how to enable the sandbox can be found at the link above, or in the [SandboxTest PowerShell Script Documentation](tools/SandboxTest.md). The [SandboxTest PowerShell Script](/Tools/SandboxTest.ps1) is a great way to get the AppsAndFeaturesEntries for a manifest you have already created. The SandboxTest Script will validate and test the manifest by downloading and installing the package in the Sandbox and comparing the ARP Entries before and after the installation. For the technically savvy, @jedieaston has created an [Add-ARPEntries Script](https://github.com/jedieaston/Add-ARPEntries) which uses Docker to populate the AppsAndFeaturesEntries for an existing manifest. Please note, however, that only the ARP Entry for the *Primary Component* should be added when a package installs multiple components.
The best way to get the AppsAndFeaturesEntries, or the ARP Entries, for an installer is to run the installer inside of the [Windows Sandbox](https://docs.microsoft.com/windows/security/threat-protection/windows-sandbox/windows-sandbox-overview). Instructions on how to enable the sandbox can be found at the link above, or in the [SandboxTest PowerShell Script Documentation](tools/SandboxTest.md). The [SandboxTest PowerShell Script](../Tools/SandboxTest.ps1) is a great way to get the AppsAndFeaturesEntries for a manifest you have already created. The SandboxTest Script will validate and test the manifest by downloading and installing the package in the Sandbox and comparing the ARP Entries before and after the installation. For the technically savvy, @jedieaston has created an [Add-ARPEntries Script](https://github.com/jedieaston/Add-ARPEntries) which uses Docker to populate the AppsAndFeaturesEntries for an existing manifest. Please note, however, that only the ARP Entry for the *Primary Component* should be added when a package installs multiple components.
## **What should I do if a package is being published by a new publisher?**
The best practice for this is to create a situation where the package automatically switches to the new publisher using the ARP Entries for the package. To do this, two copies of the package must be added to the repository - one under the original package identifier and one under a new package identifier for the new publisher. This will cause anyone on a package published by the old publisher to be updated to the new version, at which point the ARP Entries will cause the Windows Package Manager to match the package to the new publisher and all future updates will be taken from the new package identifier.

Expand All @@ -40,7 +40,7 @@ While this is currently the best practice, this may change in the future with th
## **How long do packages take to be published?**
The answer to this question depends on multiple factors. First, the pull request approval. When submitting a package to the repository, your pull request will go through a series of automated checks in the validation pipeline. You will see labels applied to your pull request based on the results of the validation. Secondly, all pull requests must be reviewed and approved by one of our [community moderators](Moderation.md). Finally, the pull request must be merged and pass through the publishing pipeline. Once the publishing pipeline has succeeded for your pull request, you will see a comment and a label indicating this status.

After your PR is approved and merged, the changes are *generally* published within one hour. If you are not seeing the changes published after your pull request has been merged, check the [WinGetSvc-Publish Pipeline](https://dev.azure.com/ms/winget-pkgs/_build?definitionId=338) for errors. If the pipeline is erroring, please check to see if any [issues](https://github.com/microsoft/winget-pkgs/issues) have been opened regarding the failures and create a [new issue](https://github.com/microsoft/winget-pkgs/issues/new) if there isn't one already.
After your PR is approved and merged, the changes are *generally* published within one hour. If you are not seeing the changes published after your pull request has been merged, check the [WinGetSvc-Publish Pipeline](https://dev.azure.com/shine-oss/winget-pkgs/_build?definitionId=12) for errors. If the pipeline is erroring, please check to see if any [issues](https://github.com/microsoft/winget-pkgs/issues) have been opened regarding the failures and create a [new issue](https://github.com/microsoft/winget-pkgs/issues/new) if there isn't one already.
## **What does this label on my PR mean?**
During the automated validation process, labels are added to pull requests to help the bots that manage the repository and the status of open requests. All of these labels are described in more detail on the [Microsoft Documentation Site](https://docs.microsoft.com/windows/package-manager/package/winget-validation#pull-request-labels)
## **Why does a package have the version "Unknown"?**
Expand Down
2 changes: 1 addition & 1 deletion doc/Moderation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The Windows Package Manager community repository is the location for manifests p

## Moderators

In addition to Microsoft employees, several community members have been identified through their high-quality submissions, willingness to help others, and adherence to our [code of conduct](/CODE_OF_CONDUCT.md).
In addition to Microsoft employees, several community members have been identified through their high-quality submissions, willingness to help others, and adherence to our [code of conduct](../CODE_OF_CONDUCT.md).

When we initially implemented moderation, we observed several objective criteria. These included the number of Pull Requests (PR)s made, the length of time they had been active in the project, and their interaction with others who submitted PRs.

Expand Down
7 changes: 6 additions & 1 deletion doc/Troubleshoot.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
# Troubleshooting Errors

Many of the issues can be caught before submitting your PR, if you follow these steps:
1) Validate the manifest file by running ```winget validate <path-to-the-manifest>```
2) Install the manifest on your local machine. This will verify the Sha256 Hash and check whether the application is able to install silently (without any human interaction) or not. You can do this by running: ```winget install --manifest <path-to-the-manifest>``` or ```winget install -m <path-to-the-manifest>```

Once those steps pass, here are some troubleshooting tips:

## Manifest-Validation-Error

Manifest validation errors indicate that there is a problem with the manifest file. Many of the issues can be caught before submitting your PR, when you validate the manifests before submission: ```winget validate <path-to-the-manifest>```

For documentation on the manifest specification, please see the [manifest schema](/doc/manifest/README.md)
For documentation on the manifest specification, please see the [manifest schema](manifest/README.md)

Here are some common mistakes not discovered by the winget validation.

Expand All @@ -31,6 +33,7 @@ Filenames:
- Version: `<PackageIdentifier>.yaml`

## Binary-Validation-Error

Binary validation errors indicate that the installer failed static analysis.

Here are some common causes for the Binary-Validation-Error label:
Expand All @@ -39,7 +42,9 @@ Here are some common causes for the Binary-Validation-Error label:
3) The installer has been identified as malware. If the installer is detected as malware, you can submit the installer to the defender team for [analysis](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-antivirus/antivirus-false-positives-negatives#submit-a-file-to-microsoft-for-analysis) as a potential false positive.

## SmartScreen-Validation-Error

Windows Defender SmartScreen validation errors indicate that the URL you provided has a bad reputation.

## Internal-Error

Internal-Errors indicate there was an error hit by the service. Microsoft will investigate these and pursue a fix. For a list of known issues, see our repository [issues](https://github.com/microsoft/winget-pkgs/issues)
1 change: 0 additions & 1 deletion doc/manifest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ The community repository will often delay support for new schema versions until
* [1.6.0 (deprecated)](schema/1.6.0/README.md)
* [1.5.0 (deprecated)](schema/1.5.0/README.md)
* [1.4.0 (deprecated)](schema/1.4.0/README.md)
* [1.3.0 (deprecated)](schema/1.3.0/README.md)
* [1.2.0 (deprecated)](schema/1.2.0/README.md)
* [1.1.0 (deprecated)](schema/1.1.0/README.md)
* [1.0.0 (deprecated)](schema/1.0.0/README.md)
2 changes: 1 addition & 1 deletion doc/manifest/schema/1.0.0/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[versionSchema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.version.1.0.0.json
[defaultLocaleSchema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.defaultLocale.1.0.0.json
[localeSchema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.locale.1.0.0.json
[installerSchema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.1.0/manifest.installer.1.0.0.json
[installerSchema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.installer.1.0.0.json

# Windows Package Manager
## Manifest Schema 1.0
Expand Down
2 changes: 1 addition & 1 deletion doc/manifest/schema/1.0.0/defaultLocale.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[JSON schema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.defaultLocale.1.0.0.json
[YAML]: https://yaml.org/spec/
[Manifest Specification]: https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv1.0.md
[Manifest Specification]: https://github.com/microsoft/winget-pkgs/blob/master/doc/manifest/README.md
[semantic version]: https://semver.org
[Available languages for Windows]: https://docs.microsoft.com/windows-hardware/manufacture/desktop/available-language-packs-for-windows
[Default Input Profiles Input Locales in Windows]: https://docs.microsoft.com/windows-hardware/manufacture/desktop/default-input-locales-for-windows-language-packs
Expand Down
4 changes: 2 additions & 2 deletions doc/manifest/schema/1.0.0/installer.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[JSON Schema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.installer.1.0.0.json
[Manifest Specification]: https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv1.0.md
[Manifest Specification]: https://github.com/microsoft/winget-pkgs/blob/master/doc/manifest/README.md
[Windows Package Manager Manifest Creator]: https://github.com/microsoft/winget-create
[YAML]: https://yaml.org/spec
[semantic version]: https://semver.org
Expand All @@ -10,7 +10,7 @@
[Inno]: https://jrsoftware.org/isinfo.php
[Nullsoft]: https://sourceforge.net/projects/nsis
[WiX]: https://wixtoolset.org
[Burn]: https://wixtoolset.org/documentation/manual/v3/bundle
[Burn]: https://wixtoolset.org/docs/v3/bundle/

# Windows Package Manager
## Manifest Schema v1.0.0 Installer File
Expand Down
2 changes: 1 addition & 1 deletion doc/manifest/schema/1.0.0/version.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[JSON schema]: https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.version.1.0.0.json
[YAML]: https://yaml.org/spec
[semantic version]: https://semver.org
[Manifest Specification]: https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv1.0.md
[Manifest Specification]: https://github.com/microsoft/winget-pkgs/blob/master/doc/manifest/README.md

# Windows Package Manager
## Manifest Schema v1.0.0 Version File
Expand Down
2 changes: 1 addition & 1 deletion doc/manifest/schema/1.1.0/installer.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
[Inno]: https://jrsoftware.org/isinfo.php
[Nullsoft]: https://sourceforge.net/projects/nsis
[WiX]: https://wixtoolset.org
[Burn]: https://wixtoolset.org/documentation/manual/v3/bundle
[Burn]: https://wixtoolset.org/docs/v3/bundle/

# Windows Package Manager
## Manifest Schema v1.1.0 Installer File
Expand Down
2 changes: 1 addition & 1 deletion doc/manifest/schema/1.1.0/singleton.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
[Inno]: https://jrsoftware.org/isinfo.php
[Nullsoft]: https://sourceforge.net/projects/nsis
[WiX]: https://wixtoolset.org
[Burn]: https://wixtoolset.org/documentation/manual/v3/bundle
[Burn]: https://wixtoolset.org/docs/v3/bundle/
[Windows Package Manager Manifest Creator]: https://github.com/microsoft/winget-create
[App capability declarations]: https://docs.microsoft.com/windows/uwp/packaging/app-capability-declarations

Expand Down
Loading

0 comments on commit 509f52b

Please sign in to comment.