Documentation Improvements (microsoft#144543)

Co-authored-by: Muhammad Danish <mdanishkhdev@gmail.com>
Co-authored-by: Kaleb Luedtke <trenlymc@gmail.com>

Author: 3 people

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,11 @@
+Checklist for Pull Requests
 - [ ] Have you signed the [Contributor License Agreement](https://cla.opensource.microsoft.com/microsoft/winget-pkgs)?
+- [ ] Is there a linked Issue
+
+Manifests
 - [ ] Have you checked that there aren't other open [pull requests](https://github.com/microsoft/winget-pkgs/pulls) for the same manifest update/change?
 - [ ] This PR only modifies one (1) manifest
-- [ ] Have you [validated](https://github.com/microsoft/winget-pkgs/blob/master/AUTHORING_MANIFESTS.md#validation) your manifest locally with `winget validate --manifest <path>`?
+- [ ] Have you [validated](https://github.com/microsoft/winget-pkgs/blob/master/doc/Authoring.md#validation) your manifest locally with `winget validate --manifest <path>`?
 - [ ] Have you tested your manifest locally with `winget install --manifest <path>`?
 - [ ] Does your manifest conform to the [1.6 schema](https://github.com/microsoft/winget-pkgs/tree/master/doc/manifest/schema/1.6.0)?
 

.github/actions/spelling/allow.txt

@@ -20,6 +20,8 @@ Inno
 INSTALLPATH
 ISVs
 Komac
+lexographic
+lexographically
 LOGPATH
 malware
 Mariocube

.github/actions/spelling/expect.txt

@@ -20,6 +20,7 @@ misclicks
 msft
 quhxl
 redistribution
+Repology
 russellbanks
 Tbot
 timezone

README.md

@@ -10,80 +10,21 @@ This repository contains the manifest files for the **Windows Package Manager**
 > [!IMPORTANT]
 > At this time installers must be MSIX, MSI, APPX, or .exe application installers. Script-based installers and fonts are not currently supported.
 
-The **Windows Package Manager** is an [open source client](https://github.com/microsoft/winget-cli) designed for command-line usage. If you are interested in exploring third-party repositories offering private winget package hosting, see [third-party repositories](THIRD_PARTY.md).
+The **Windows Package Manager** is an [open source client](https://github.com/microsoft/winget-cli) designed for command-line usage. If you are interested in exploring private repositories offering private WinGet package hosting, see [private repositories](doc/private/README.md).
 
-# Submitting a Package
+# Documentation
 
-To submit a package to this repository, you should follow these steps:
+Please check the [overview](doc/README.md) for detailed topics. Common topics for the WinGet Community repository are available below:
+* [Authoring a manifest](doc/README.md#authoring-a-manifest)
+* [Testing a manifest](doc/README.md#testing-a-manifest)
+* [Submitting a manifest](doc/README.md#submitting-a-manifest)
+* [Requesting a new package](doc/Issues.md#Request-a-New-Package)
+* [Requesting a new package version](doc/Issues.md#Request-a-New-Package-Version)
 
-1. Follow the [Contributing](#contributing) guidelines below.
-2. [Author](AUTHORING_MANIFESTS.md) a Manifest.
-3. [Test](#test-your-manifest) your manifest.
-4. [Submit](#submit-your-pr) your pull request (PR).
-5. Respond to any feedback in your PR.
+## Repology
+[Repology](https://repology.org/), the packaging hub monitors package repositories comparing package versions and other information.
 
-> Note: Please check the package's manifest you intend to submit does not already exist in the repository, and there are no open PRs for it in order to avoid duplicates.
-
-## Authoring a Manifest
-
-A few different tools are available to help you author a manifest.
-
-- [Windows Package Manager Manifest Creator](https://github.com/microsoft/winget-create)
-- [YamlCreate.ps1](doc/tools/YamlCreate.md)
-- Other WinGet Manifest Creators developed by the community:
-  - [Komac - Community Manifest Creator](https://github.com/russellbanks/Komac) (maintained by [**@russellbanks**](https://github.com/russellbanks))
-
-> Note: Only one manifest may be submitted per PR.
-
-## Test your manifest
-
-Now that you have authored your manifest, you should make sure it works as expected.
-
-> Note: You will need to run `winget settings --enable LocalManifestFiles` in an administrative shell before working with local manifests.
-
-### Locally
-
-1. Verify the syntax by executing the following command:
-
-```
-winget validate --manifest <path-to-manifest>
-```
-
-2. Test the install by executing the following command:
-
-```
-winget install --manifest <path-to-manifest>
-```
-
-For more details, see ["Submit packages to Windows Package Manager"](https://docs.microsoft.com/windows/package-manager/package) at Microsoft Docs.
-
-### In Windows Sandbox
-
-You can use the [Sandbox Test](Tools/SandboxTest.ps1) PowerShell script for testing a manifest installation in [Windows Sandbox](https://docs.microsoft.com/windows/security/threat-protection/windows-sandbox/windows-sandbox-overview). The manifest will be also validated.
-
-Just provide the path to manifest as parameter:
-
-```
-.\Tools\SandboxTest.ps1 <path-to-manifest>
-```
-
-## Submit your PR
-
-Once you have verified your manifest, it's time to submit a PR. Place your manifest in a folder path that matches the following structure:
-
-```
-manifests\<first lower case letter of publisher>\<publisher>\<package>\<version>\
-```
-
-### Validation Process
-
-Your PR will go through a validation process. The core team or the Microsoft bot (BOT) will use  [labels](https://docs.microsoft.com/windows/package-manager/package/winget-validation#pull-request-labels)  to assist during the process. In case of a failure, the BOT will suggest the problem with the submission and assign the PR back to you.
-
-### Respond to PR feedback
-
-If your PR has been assigned to you, a timer will be triggered. You will have 7 days to resolve the issue, or the BOT will automatically close the PR.
-
-Submissions to the repository are reviewed by Windows Package Manager administrators and/or community moderators. To help identify these individuals, we have provided a  [Public Service Announcement](https://github.com/microsoft/winget-pkgs/issues/15674).
+[![Repository status](https://repology.org/badge/repository-big/winget.svg)](https://repology.org/repository/winget)
 
 # Contributing
 

Tools/YamlCreate.ps1

@@ -168,7 +168,7 @@ if ($Settings) {
   exit
 }
 
-$ScriptHeader = '# Created with YamlCreate.ps1 v2.3.5'
+$ScriptHeader = '# Created with YamlCreate.ps1 v2.4.0'
 $ManifestVersion = '1.6.0'
 $PSDefaultParameterValues = @{ '*:Encoding' = 'UTF8' }
 $Utf8NoBomEncoding = New-Object System.Text.UTF8Encoding $False
@@ -2059,108 +2059,114 @@ Function Read-LocaleMetadata {
 # Uses this template and responses to create a PR
 Function Read-PRBody {
   $PrBodyContent = Get-Content $args[0]
-  ForEach ($_line in ($PrBodyContent | Where-Object { $_ -like '-*[ ]*' })) {
-    $_showMenu = $true
-    switch -Wildcard ( $_line ) {
-      '*CLA*' {
-        if ($ScriptSettings.SignedCLA -eq 'true') {
-          $PrBodyContentReply += @($_line.Replace('[ ]', '[X]'))
-          $_showMenu = $false
-        } else {
+  ForEach ($_line in $PrBodyContent) {
+    # | Where-Object { $_ -like '-*[ ]*' }))
+    if ($_line -like '-*[ ]*' )
+    {
+      $_showMenu = $true
+      switch -Wildcard ( $_line ) {
+        '*CLA*' {
+          if ($ScriptSettings.SignedCLA -eq 'true') {
+            $PrBodyContent = $PrBodyContent.Replace($_line,$_line.Replace('[ ]','[x]'))
+            $_showMenu = $false
+          } else {
+            $_menu = @{
+              Prompt        = 'Have you signed the Contributor License Agreement (CLA)?'
+              Entries       = @('[Y] Yes'; '*[N] No')
+              HelpText      = 'Reference Link: https://cla.opensource.microsoft.com/microsoft/winget-pkgs'
+              HelpTextColor = ''
+              DefaultString = 'N'
+            }
+          }
+        }
+
+        '*open `[pull requests`]*' {
           $_menu = @{
-            Prompt        = 'Have you signed the Contributor License Agreement (CLA)?'
+            Prompt        = "Have you checked that there aren't other open pull requests for the same manifest update/change?"
             Entries       = @('[Y] Yes'; '*[N] No')
-            HelpText      = 'Reference Link: https://cla.opensource.microsoft.com/microsoft/winget-pkgs'
+            HelpText      = 'Reference Link: https://github.com/microsoft/winget-pkgs/pulls'
             HelpTextColor = ''
             DefaultString = 'N'
           }
         }
-      }
 
-      '*open `[pull requests`]*' {
-        $_menu = @{
-          Prompt        = "Have you checked that there aren't other open pull requests for the same manifest update/change?"
-          Entries       = @('[Y] Yes'; '*[N] No')
-          HelpText      = 'Reference Link: https://github.com/microsoft/winget-pkgs/pulls'
-          HelpTextColor = ''
-          DefaultString = 'N'
+        '*winget validate*' {
+          if ($? -and $(Get-Command 'winget' -ErrorAction SilentlyContinue)) {
+            $PrBodyContent = $PrBodyContent.Replace($_line,$_line.Replace('[ ]','[x]'))
+            $_showMenu = $false
+          } elseif ($script:Option -ne 'RemoveManifest') {
+            $_menu = @{
+              Prompt        = "Have you validated your manifest locally with 'winget validate --manifest <path>'?"
+              Entries       = @('[Y] Yes'; '*[N] No')
+              HelpText      = 'Automatic manifest validation failed. Check your manifest and try again'
+              HelpTextColor = 'Red'
+              DefaultString = 'N'
+            }
+          } else {
+            $_showMenu = $false
+          }
         }
-      }
 
-      '*winget validate*' {
-        if ($? -and $(Get-Command 'winget' -ErrorAction SilentlyContinue)) {
-          $PrBodyContentReply += @($_line.Replace('[ ]', '[X]'))
-          $_showMenu = $false
-        } elseif ($script:Option -ne 'RemoveManifest') {
-          $_menu = @{
-            Prompt        = "Have you validated your manifest locally with 'winget validate --manifest <path>'?"
-            Entries       = @('[Y] Yes'; '*[N] No')
-            HelpText      = 'Automatic manifest validation failed. Check your manifest and try again'
-            HelpTextColor = 'Red'
-            DefaultString = 'N'
+        '*tested your manifest*' {
+          if ($script:SandboxTest -eq '0') {
+            $PrBodyContent = $PrBodyContent.Replace($_line,$_line.Replace('[ ]','[x]'))
+            $_showMenu = $false
+          } elseif ($script:Option -ne 'RemoveManifest') {
+            $_menu = @{
+              Prompt        = "Have you tested your manifest locally with 'winget install --manifest <path>'?"
+              Entries       = @('[Y] Yes'; '*[N] No')
+              HelpText      = 'You did not test your Manifest in Windows Sandbox previously.'
+              HelpTextColor = 'Red'
+              DefaultString = 'N'
+            }
+          } else {
+            $_showMenu = $false
           }
-        } else {
-          $_showMenu = $false
-          $PrBodyContentReply += @($_line)
         }
-      }
 
-      '*tested your manifest*' {
-        if ($script:SandboxTest -eq '0') {
-          $PrBodyContentReply += @($_line.Replace('[ ]', '[X]'))
-          $_showMenu = $false
-        } elseif ($script:Option -ne 'RemoveManifest') {
-          $_menu = @{
-            Prompt        = "Have you tested your manifest locally with 'winget install --manifest <path>'?"
-            Entries       = @('[Y] Yes'; '*[N] No')
-            HelpText      = 'You did not test your Manifest in Windows Sandbox previously.'
-            HelpTextColor = 'Red'
-            DefaultString = 'N'
+        '*schema*' {
+          if ($script:Option -ne 'RemoveManifest') {
+            $_Match = ($_line | Select-String -Pattern 'https://+.+(?=\))').Matches.Value
+            $_menu = @{
+              Prompt        = $_line.TrimStart('- [ ]') -replace '\[|\]|\(.+\)', ''
+              Entries       = @('[Y] Yes'; '*[N] No')
+              HelpText      = "Reference Link: $_Match"
+              HelpTextColor = ''
+              DefaultString = 'N'
+            }
+          } else {
+            $_showMenu = $false
           }
-        } else {
+        }
+
+        '*only modifies one*' {
+          $PrBodyContent = $PrBodyContent.Replace($_line,$_line.Replace('[ ]','[x]'))
           $_showMenu = $false
-          $PrBodyContentReply += @($_line)
         }
-      }
 
-      '*schema*' {
-        if ($script:Option -ne 'RemoveManifest') {
-          $_Match = ($_line | Select-String -Pattern 'https://+.+(?=\))').Matches.Value
+        '*linked issue*' {
+          # Linked issues is handled as a separate prompt below so that the issue numbers can be gathered
+          $_showMenu = $false
+        }
+
+        Default {
           $_menu = @{
-            Prompt        = $_line.TrimStart('- [ ]') -replace '\[|\]|\(.+\)', ''
+            Prompt        = $_line.TrimStart('- [ ]')
             Entries       = @('[Y] Yes'; '*[N] No')
-            HelpText      = "Reference Link: $_Match"
+            HelpText      = ''
             HelpTextColor = ''
             DefaultString = 'N'
           }
-        } else {
-          $_showMenu = $false
-          $PrBodyContentReply += @($_line)
         }
       }
 
-      '*only modifies one*' {
-        $PrBodyContentReply += @($_line.Replace('[ ]', '[X]'))
-        $_showMenu = $false
-      }
-
-      Default {
-        $_menu = @{
-          Prompt        = $_line.TrimStart('- [ ]')
-          Entries       = @('[Y] Yes'; '*[N] No')
-          HelpText      = ''
-          HelpTextColor = ''
-          DefaultString = 'N'
+      if ($_showMenu) {
+        switch ( Invoke-KeypressMenu -Prompt $_menu['Prompt'] -Entries $_menu['Entries'] -DefaultString $_menu['DefaultString'] -HelpText $_menu['HelpText'] -HelpTextColor $_menu['HelpTextColor']) {
+          'Y' { $PrBodyContent = $PrBodyContent.Replace($_line,$_line.Replace('[ ]','[x]')) }
+          default { }
         }
       }
     }
-
-    if ($_showMenu) {
-      switch ( Invoke-KeypressMenu -Prompt $_menu['Prompt'] -Entries $_menu['Entries'] -DefaultString $_menu['DefaultString'] -HelpText $_menu['HelpText'] -HelpTextColor $_menu['HelpTextColor']) {
-        'Y' { $PrBodyContentReply += @($_line.Replace('[ ]', '[X]')) }
-        default { $PrBodyContentReply += @($_line) }
-      }
-    }
   }
 
   # Request user to enter if there were any issues resolved by the PR
@@ -2171,11 +2177,14 @@ Function Read-PRBody {
   }
   switch ( Invoke-KeypressMenu -Prompt $_menu['Prompt'] -Entries $_menu['Entries'] -DefaultString $_menu['DefaultString']) {
     'Y' {
+      $_line = ($PrBodyContent | Select-String 'linked issue').Line
+      if ($_line) { $PrBodyContent = $PrBodyContent.Replace($_line,$_line.Replace('[ ]','[x]')) }
+
       # If there were issues resolved by the PR, request user to enter them
       Write-Host
       Write-Host "Enter issue number. For example`: 21983, 43509"
       $ResolvedIssues = Read-Host -Prompt 'Resolved Issues' | UniqueItems
-      $PrBodyContentReply += @('')
+      $PrBodyContent += @('')
 
       # Validate each of the issues entered by checking the URL to ensure it returns a 200 status code
       Foreach ($i in ($ResolvedIssues.Split(',').Trim())) {
@@ -2199,15 +2208,15 @@ Function Read-PRBody {
             Write-Host -ForegroundColor 'Red' "Invalid Issue: $i"
             continue
           }
-          $PrBodyContentReply += @("Resolves $i")
+          $PrBodyContent += @("Resolves $i")
         } else {
           $_checkedURL = "https://github.com/microsoft/winget-pkgs/issues/$i"
           $_responseCode = Test-Url $_checkedURL
           if ($_responseCode -ne 200) {
             Write-Host -ForegroundColor 'Red' "Invalid Issue: $i"
             continue
           }
-          $PrBodyContentReply += @("* Resolves #$i")
+          $PrBodyContent += @("* Resolves #$i")
         }
       }
     }
@@ -2216,11 +2225,11 @@ Function Read-PRBody {
 
   # If we are removing a manifest, we need to include the reason
   if ($CommitType -eq 'Remove') {
-    $PrBodyContentReply = @("## $($script:RemovalReason)"; '') + $PrBodyContentReply
+    $PrBodyContent = @("## $($script:RemovalReason)"; '') + $PrBodyContent
   }
 
   # Write the PR using a temporary file
-  Set-Content -Path PrBodyFile -Value $PrBodyContentReply | Out-Null
+  Set-Content -Path PrBodyFile -Value $PrBodyContent | Out-Null
   gh pr create --body-file PrBodyFile -f
   Remove-Item PrBodyFile
 }